-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation structure #63
Comments
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 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 This would let us have separate sections with separate side-bar contents. (Though they get combined into one menu on mobile/small viewports.) |
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.
The text was updated successfully, but these errors were encountered: