mkdocs-rc-docs
mkdocs-rc-docs copied to clipboard
UCL-RITS
Documentation structure
At the moment we have a lot in our top-level navigation that ended up there by default and wasn't thought about whether that was the appropriate place to put it (eg Where do my results go? and the quickstart guides - which are also different types of documentation).
Are the guides useful in their current form?
Quickstart guide for experiences users is a reference, guide for new users is a how to.
How tos should be specific and self-contained and intended to be followed start to finish, should stand on their own. Reference to dip into as needed.
No longer have an FAQ - some of this is in the how tos page. Have a look at NASA FAQ.
Linked: NASA HECC: https://www.nas.nasa.gov/hecc/support/kb/ TACC: https://docs.tacc.utexas.edu/
Supplementary directory needs to be checked, some old stuff just left in there. (Troubleshooting page should probably be in FAQs?)
Other Software is not easily found and not linked from Example Jobscripts.
Example script in repo that be generated into docs for each piece of software. (We already have one of those, currently used by OOD stuff). get_example application to get the example jobscript that you can run.
Info on requesting access to applications isn't mentioned with the docs for those applications.
Improve interactive jobs page (mention cluster-specific info exists?)
Identify if some of our "general" pages are really only about Myriad and have significant differences for Kathleen/Young etc.
- [ ] Outline of what structure we have now, and some design principles so we know where new things should be added when they come up.
As an additional example: EPCC's ARCHER2 documentation is split between a MkDocs site and their more "official"-looking CMS site. They have that whole site for just ARCHER2, though, because of the connected projects.
The philosophy for the NASA FAQs seems to have been that the Q s correspond to common tasks for researchers in plain language with no jargon ("Why won't my job start?") and then the A s use the specific vocabulary and name the command line tools that can be used to accomplish the task (in this example, using qstat and their homebrew accounting tools to inspect the status of a job).
Our articles listed under the Guide for New Users and some of the How To page are serving this purpose at the moment.
This is the feature in MkDocs I mentioned, the ability to hoist the top level of navigation into the top-bar: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs.
(You can quickly try stuff like this using mkdocs serve from the directory containing the mkdocs.yml file.)
This would let us have separate sections with separate side-bar contents. (Though they get combined into one menu on mobile/small viewports.)