Add additional documentation markdown to services (and domains)

[robennett2]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

It would be nice to be able to add docs to a service, we currently have documentation for services within a wiki on Azure Devops and it would be great to be able to migrate this over and have it in one place.

It would be nice to be able to have this folder structure in a service folder like this: and then use a md component like <DocsContentsList /> which would essentially output a table of contents like this:

Motivation

Would allow structured documentation to be added to services and domains. This would allow an event catalog site to be used as a full documentation site that allows structuring rather then specifically events.

[boyney123]

Hi @robertbennett1998,

Thanks for raising the issue on Discord and here 🙏, yeah I quite like the idea, not really considered this before, and could be quite flexible for people. Looks like over on Discord others might be interested in this too.

Maybe for the initial version, we could support just the markdown files (without MDX components), and as you said a new docs (optional) inside the service/events could make sense... although the main doc index.md would be in the root with docs folder might get confusing... so maybe another word vs docs might be better? What you think? cc: @otbe @thim81

[robennett2]

The way I was looking at it is index.md is essentially your landing page and then the docs folder would contain specific documentation. For example, for a service my index.md might list all of the databases that the service uses and then there might be a specific "doc page" in the docs folder for each one which might explain the structure ect.

Maybe children / pages would be a better word then "docs" as that is essentially what they are.