document the documentation management process - Githubissues

microbiomedata / NMDC_documentation

Document workflows, schemas, and portal

https://nmdc-documentation.readthedocs.io

2 stars 3 forks source link

document the documentation management process #8

Open turbomam opened 2 years ago

turbomam commented 2 years ago

I would like to learn how to contribute to NMDC docuemtnation, and also to help others discuss this process with better shared understanding.

[ ] what does this repo do?
[ ] how is it triggered or executed?
- manually visiting the ReadTheDocs website and clicking a build button?
- could that be automated?
- are GitHub actions being used at all?
- is anything being deployed to GitHub pages?
- in what ways is this integrated with the NMDC Data Portal?
[ ] where should new input go?
- one of the Diataxis-themed folders in doc/, like
- explanation
- howto_guides
- overview
- reference

Do we have official titles for the various places where aggregated documentation may appear?

Various buzzwords I have heard in connection with this effort:

ReadTheDocs, RTD
reStructuredText, RST
- Which is preferred, MarkDown or RST? I mostly see MD in this repo.
Sphinx
- Are we really generating any documentation pages from comments in Python scripts? how does that get integrated into this repo?