Update schema documentation

[ssarrafan]

Tasks related to schema docs:

• https://microbiomedata.github.io/nmdc-schema/about/
• https://microbiomedata.github.io/nmdc-schema/identifiers/
• https://microbiomedata.github.io/nmdc-schema/prefixes_curies_ids_mappings_etc/
• https://microbiomedata.github.io/nmdc-schema/Metadata_Documentation_Overview/
• https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693
• https://microbiomedata.github.io/nmdc-schema/schema-validation/
• https://microbiomedata.github.io/nmdc-schema/schema_element_deprecation_guide/
• https://microbiomedata.github.io/nmdc-schema/schema_element_deprecation_guide/
• https://microbiomedata.github.io/nmdc-schema/v10-vs-v11-retrospective/
• https://microbiomedata.github.io/nmdc-schema/visualizations/

[ssarrafan]

Slacked @cmungall to see who should be updating these today.

[ssarrafan]

@sierra-moxon @turbomam @emileyfadrosh any suggestions on who can review/update the schema related documentation?

[ssarrafan]

No response. Very Sad. Will move to next sprint and add a Slack discussion about this. @cmungall @emileyfadrosh

[sierra-moxon]

I can take a look through the checklist and make some progress.

[turbomam]

I can help as much or as little as you want @sierra-moxon

My goals:

• generation of documentation web pages should be automated/autogenerated
• we should review old documentation pages that were a hybrid of gen-doc content and custom commentary. @eecavanna should be able to help find that. I think it was managed as a ReadTheDocs website.
• maybe the schema repo needs a catalog of the different documentation entry points ?
• ideally we should have one place for each kind of documentation and provide links between the various files and pages as necessary
• we should test whether the documentation still "works" though automation or by having people who don't frequently work on the schema try their hand at some explicit or implicit exercises
• there shouldn't be any errors or contradictions between files/pages!

[turbomam]

@set the original post in this issue is a list of custom documentation pages (ie not gen-doc created). Can you say whether the "my goals" post above this is compatible with the goals as you understand them?

I'll look at the project boards now.

[ssarrafan]

Discussed with @turbomam today. For this month the goal is to make sure the current links and info for public facing documentation is accurate and correct.

In the future we will follow-up about whether we need to move any of these or any other schema related docs.

[sierra-moxon]

ok I made lots of changes and PR - let me know if I am on the right track? you can see the preview of my changes here: https://microbiomedata.github.io/nmdc-schema/pr-preview/pr-2317/

summary:

• reorg the index so that it does a tiny bit of hiding of developer/internal doc like "how to collaborate" and "migration guides" - add a developer FAQ index to link tooling
• add a Contributing doc page that encourages open source development
• add in logos, favicons, header icons for styling
• add some high-level text to the schema description and overview pages to help folks new to the project understand the context of this doc.

[emileyfadrosh]

@sierra-moxon this looks fantastic! Just what is needed, thank you!

[ssarrafan]

@sierra-moxon @turbomam I'm going to move this over to new sprint for Mark to review.

[ssarrafan]

Considering this done for the Jan documentation updates. Thanks @sierra-moxon