Update user guide

[kinow]

The goal of this issue is to update the user guide, making it a comprehensive reference material, not a tutorial or tutorial material.

The format will be different than the Carpentries format. The first tentative version will be created with Sphinx + markdown + ReadTheDocs. While these tools can still be replaced by others, the goal is to create a low entry barrier for new contributors (e.g. instead of having to learn reStructuredText, use simpler Markdown.)

This is a placeholder issue, and existing issues will be linked here. A few important pointers:

• This user guide will be integrated with the CWL site, like the existing one
• It is important to keep links working (for SEO, bookmarks, etc.)
• Should have GH pull requests preview

Contributions & any other help very welcome! Feel free to link this issue to other issues 🚢

[kinow]

MyST syntax cheatsheet from JupyterHub: https://jupyterbook.org/reference/cheatsheet.html

[kinow]

I normally use Draw.io and Inkspace, but looks like Draw.io has a new home, and found another interesting (free) tool too:

• https://mermaid-js.github.io/mermaid-live-editor/
• https://app.diagrams.net/

Of course if we can use cwltool or the Viewer, then we will use that. But if we need a diagram to illustrate something else, maybe one of the above could be useful (or Inkscape + SVG to store it on GitHub).

[kinow]

Numpy, Canonical, and others are using Diátaxis for guiding how to organize their documentation: https://diataxis.fr/

There are four main axis in Diátaxis, which I believe we have adopted in the proposed new structure #222, even if not following Diátaxis initially:

1. Explanations (our User Guide)
2. How-to guides (links in the How-Tos section of the User Guide)
3. Tutorials (links in the Tutorial section of the User Guide)
4. Reference material (the Specification)

I will spend some more time reading about it, and about how others have used it to see if there's more that we can incorporate into our user guide.

[kinow]

For later, I will try to go over Discourse & Matrix to see if the new version of the user guide has sections for the answers for user's questions. I saw a post in the Cylc discourse that reminded me they also re-wrote their user guide (but due to a new release) and now they are able to link to it to answer users 🙂

(the links in the image above are to sections of the Cylc User Guide)

I will also take a look at their user guide structure, text, and especially at their Sphinx set-up (I hadn't used much Sphinx before, and learned most of what I know from working with the Cylc devs 🙇 ). Even though we are now using Sphinx + MyST, I believe most (if not all) Sphinx/rst extensions are compatible with MyST.

[kinow]

Closing now. We can work on smaller issues for future corrections and improvements.