Add a human readable reference guide explaining the project YAML parameters

[StroemPhi]

Spun out of a Slack discussion, we've identified the need to have a more practical overview of what project.YAML parameters are available and how to set them, based on https://github.com/INCATools/ontology-development-kit/blob/master/docs/project-schema.md.

[StroemPhi]

Is related to #866

[pfabry]

As a first step, maybe we could make project-schema.md more visible for ODK users? Personally, I wasn't aware of this file's content before the Slack discussion. This file (and all the markdown files in ontology-development-kit/docs in fact) should be generated iin /docs when you generate a new repo.

[StroemPhi]

I agree that having project-schema.md in the docs folder that gets generated by ODK would be really helpful. The other MDs however are mostly redirects to the OBOOK. So wouldn't it thus be better to only add one or more links to the OBOOK in the default doc templates of ODK?

[StroemPhi]

Regarding the suggested first step of exposing the project-schema.md to ODK users, I would suggest to link to it under the Where to get help section of the ODK README.

Regarding the integration into the autogenerated docs of an ODK based repo, I would add a link to the project-schema.md in a appropriate section of https://github.com/INCATools/ontology-development-kit/blob/master/template/_dynamic_files.jinja2.

Regarding fleshing out the documentation of the schema itself, I would then suggest to iterativly improve the project-schema.md, as it then serves as single point of truth. Although I wonder if it would be better to have such a more fleshed out MD live in the OBOOK instead of the ODK repo?

Any thought @matentzn or @gouttegd?

[matentzn]

Sure, if you can make a PR with a proposal, that would be great!

[StroemPhi]

point 1 & 2 from #864 (comment) are addressed in the linked PR. Regarding Point 3, before fleshing it out, I need to know, if the project-schema.md is autogenerated. Woulnd't make much sense to edit it if so.

[StroemPhi]

I specified that #879 would close this issue, as I think it would be better to open a new issue for the actual fleshing out of the schema description/documention.