Markdown based specification

[thompson-tomo]

I would like to have the specification described in markdown files which are generated automatically based upon the schema definition files.

After some research & testing it appears that https://github.com/adobe/jsonschema2md/ can be used and it won't need an additional runtime ie go/python.

The Hope is once the docs are of quality ie all titles are set, they can be published to openTelemetry.io to maximise visibility/understanding.

An example of using the tool can be seen at: https://github.com/thompson-tomo/opentelemetry-configuration/tree/feature/%23255_MarkdownDocs/docs/spec

[jack-berg]

I've had the same idea for some time now! Recently merged a variety of PRs related to what I'm calling the meta schema. Amongst the changes, we now generate schema-docs.md from information sourced from both the meta schema and JSON schema.

[thompson-tomo]

No worries have left some thoughts in #266