Improve documentation of Govspeak component

app/views/govuk_component/docs/govspeak.yml

@@ -1,5 +1,16 @@
 name: Govspeak content
-description: To display long form text which has been converted from markdown
+description: To display long form text which has been converted from Govspeak
+body: |
+  [Govspeak](https://github.com/alphagov/govspeak) is GOV.UK's extension of Markdown.
+
+  This component has no control over markup, which is passed in to the component pre-generated. It only applies CSS/JS.
+
+  It applies styling to standard Markdown content, eg; paragraphs, headings and lists. It also applies styling to Govspeak specific markup, like [callouts](https://github.com/alphagov/govspeak#callouts), [contacts](https://github.com/alphagov/govspeak#points-of-contact) and [highlights](https://github.com/alphagov/govspeak#highlights).
+
+  In addition to styling, it also applies some Javascript behaviours.
+
+  - Progressively enhanced, accessible charts (using [Magna Charta](https://github.com/alphagov/magna-charta), derived from tabular data (see example below)
+  - Progressively enhanced, accessible embedded YouTube player (using [AccessibleMediaPlayer](https://github.com/alphagov/Accessible-Media-Player)
 fixtures:
   basic_content:
     content: |
@@ -157,5 +168,5 @@ fixtures:
       <p>This content has some <strong>rich govspeak</strong></p>
   with_youtube_embed:
     content: |
-      <p>This content has a YouTube video link, converted to an accessible embedded player</p>
+      <p>This content has a YouTube video link, converted to an accessible embedded player by component JavaScript.</p>
       <p><a href="https://www.youtube.com/watch?v=y6hbrS3DheU">Operations: a developer's guide, by Anna Shipman</a></p>