Outline of how the Squonk2.0 documentation will be organised.
Categories of documentation
- End user documentation for DM UI
- Documentation for individual DM jobs
- Administrator documentation for DM and AS
- Deployment docs
- End user documentation for Pose viewer and other apps
- Support and discussion
1. End user documentation for DM UI
Markdown pages in the UI app that are included in the deployment (similar to the current landing page).
Docs would be updated as the code evolves.
- Concepts - introduce account server, organisations, units, projects, datasets etc
- Explain the different tabs - datasets, projects, executions, results, settings
- How to guides - datasets, create project, launch jupyter, run job …
2. Documentation for individual DM jobs
The job definition contains a
doc-url field that defines the URL where documentation for the job can be found. Currently this points to a Discourse post which works file, but does not make it easy to generate a complete set of docs for the jobs that are deployed. To address this we could:
- Create the documentation in the repo where the jobs are defined. e.g. a job named
assassinscollection could be documented in a file in the repo called
- Define the value of the
doc-urlfield in the job definition to point to that file.
- The UI would provide the right link without any changes.
- In the job manifest file include the URL of the repository, or record the URL when the manifest is loaded into Data Manager.
- DM provides an API that describes which manifests have been loaded (and maybe the doc URLs of the jobs in the manifest)
- UI uses info from that endpoint to collate a full list of jobs that have been deployed to that Squonk instance.
3. Administrator documentation for DM and AS
Maybe this would be handled in the same way as end user docs, though not all admin functions are related to using the UI
4. Deployment docs
Probably the detailed docs remain in the appropriate (Ansible) repos, but some hig level overview with links to those should included in the Administrator docs.
5. End user documentation for Pose viewer and other apps
To be decided, but probably similar to how the UI end user docs are handled.
6. Support and discussion
Remains in Discourse