FAIR Documentation System

[zzap]

This issue will be used to track the effort of building the documentation system for the FAIR project.

Assessment of all org repos

• Understand the system and its moving parts - FAIR project assessment for documentation system #185
• Understand which repo is doing what, who is a contributor, and who is a consumer - Documentation supply chain #204
• Locate all pieces of docs - it's a mess, and that's expected

Compile a list of requirements for the system and software #185

• Accessibility
• Open source software (its maturity, maintainability, community health, features: search, translation, contributing to docs, consuming docs, maintaining and extending the software, multiple software versions...)
• Hosing the docs
• Version control of the docs
• Automations and workflows

Discovery

• Look into large and stable open source projects, what they use and how (if possible, find out why)
• Compare to your wish list and decide on the stack

Infrastructure #205

• Install the software - Docusaurus Software for hosting documentation #219
• Make sure deployment is as simple and as short as possible (also, record and document it). Document how docs deployment works docs#21
• Start making changes to the home page and general shared elements (header and footer). Make the home page have all the branding needed, all the links to other relevant places (inner pages can stay in demo).

Workflows and automations

• Create a way for people to report problems, make sure they can contact you, and, if possible, create automation from report to github issue. This is more important than having inner pages done and docs up to date (guess what, this will never happen). - Create a way for people to report issues docs#22
• Create a way to report on the spot. No GitHub account, no additional steps, just inline suggestion that opens GitHub issue (anonymous or not, if logged into GitHub). Docs suggestion mode - Report issues on the spot docs#27
• Create issues and PR templates - Create issues and PR templates docs#23

Must-have docs

• Create documentation on contributing to the docs. This is more important than having inner pages done and docs up to date (guess what, you know what). - Create documentation on contributing to the docs docs#24
• Create documentation on general contributing to the project (code, testing, etc) DOCS - Contributing with code #186
• Create documentation on how the organisation functions (mostly done in different places) Create documentation on how the FAIR organisation functions docs#25

Docs per repo