Add documentation on spec documentation

[swallez]

Adds a doc explaining how to write and structure JSDoc documentation in the specification.

@goodroot I added you as a reviewer, feel free to add more people from the docs team to raise awareness and provide feedback.

[philkra]

Can we merge the content with this section?

[swallez]

Added a commit that that adds a link to this document in that section.

[goodroot]

Thanks @swallez 👍

Appreciate the documentation. The writing advice re: how to structure annotations to be succinct, contain a descriptive line before substantial paragraphs, is also appreciated. It is a step forward to a standard we can adopt across many contexts when generating API docs.

Pinging writers from Elasticsearch: @debadair @jrodewig @lockewritesdocs

And writers with a general interest in API docs: @KOTungseth @lcawl @kilfoyle

Folks: this PR documents how the API specifications now support GitHub Flavoured Markdown. These annotated TypeScript API specifications render down into JSON which an eventual "next docs" generator will turn into MDX doc pages. Happy to unpack in greater detail and no action is required, but feel free to leave feedback.

[delvedor]

I'm wondering if we should also add a check in the compiler to verify if the description can be parsed with GFM.

[gtback]

❤️ documentation about how to write documentation ✍🏻 .