Squonk2.0 docs reog

Squonk Data Manager Knowledge Base
#1

Outline of how the Squonk2.0 documentation will be organised.

Categories of documentation

  1. End user documentation for DM UI
  2. Documentation for individual DM jobs
  3. Administrator documentation for DM and AS
  4. Deployment docs
  5. End user documentation for Pose viewer and other apps
  6. 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.

Sections

  1. Concepts - introduce account server, organisations, units, projects, datasets etc
  2. Explain the different tabs - datasets, projects, executions, results, settings
  3. 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:

  1. Create the documentation in the repo where the jobs are defined. e.g. a job named killer-job from the assassins collection could be documented in a file in the repo called docs/assassins/killer-job.md.
  2. Define the value of the doc-url field in the job definition to point to that file.
  3. The UI would provide the right link without any changes.
  4. In the job manifest file include the URL of the repository, or record the URL when the manifest is loaded into Data Manager.
  5. DM provides an API that describes which manifests have been loaded (and maybe the doc URLs of the jobs in the manifest)
  6. 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