Documentation structure

[TomNicholas]

We should try to follow this overall structure for documentation.

(see https://docs.divio.com/documentation-system/)

Status

• [ ] Tutorials
  • [ ] I think the existing notebooks count as tutorials?
• [ ] Explanation Long-form explanation of high-level concepts
  • [ ] What C-Star aims to do for you
  • [ ] Case vs blueprint
  • [ ] Some mention of future plans of providing pre-approved blueprints
• [ ] How-to Guides
  • [ ] How to run an off-the-shelf configuration
  • [ ] How to set up your own domain from scratch
  • [ ] How to not get bottlenecked by regridding
• [ ] Reference
  • [ ] API docs can be seen here, but might need filling out a little bit (e.g. following standard formatting, adding examples and cross-links where appropriate)
  • [ ] Glossary https://github.com/CWorthy-ocean/C-Star/issues/28
• [ ] README (Rewrite to follow these recommendations)

[TomNicholas]

Notes:

• Want to link everything to everything
  • Having API docs and a glossary first would allow all written docs to have hyperlinks
• The .. Note thing in RST/myst is useful for noting things that haven't yet been implemented (see VirtualiZarr docs for lots of examples of that)
• High-level goals
  • Start from one of our existing written explanations (ask Matt for link)
  • We want a short and sweet version for the readme
  • and a more in-depth set of paragraphs for those who decide they want to read more
  • Diagrams would be worth many words
  • Development roadmap
• Prioritize?
  • Explanation
  • Use so that we're all on the same page about goals
  • Glossary
  • Highest-level concepts first
  • Architecture diagram
  • Might not want to do this too early in case it becomes outdated?
  • Mermaid diagrams can be auto-generated from code to some extent / designed to be updated
  • De-prioritize writing Roadmap until after alpha?
• Existing content
  • Split up long notebook on Using C-Star
  • Make Preparing input data for a ROMS simulation into a how-to guide?
• User vs Developer
  • Distinction between someone who uses a pre-existing blueprint vs creates a new one