Re-ordering and splitting the User Guide

[longr]

I think the user guide could do with re-ordering. I am not sure that a user just starting out would need to know docker before staging input files or array inputs for instance. I also wonder if it would be best to separate out completely of in some other way, beginner, intermediate and advanced tutorials. Some of these are beyond what I would think the basics are that you may need.

[tobyhodges]

Thanks for the suggestion, Robin. You're probably right and splitting up the chapters into different groups will also make the user guide easier to navigate - the dropdown menu of episodes is getting very long!

[mr-c]

The user guide should link prominently (perhaps in several places) to the novice tutorial. It should state that the goal of the CWL User Guide is to be reference material, for those with some CWL experience.

[kinow]

The user guide should link prominently (perhaps in several places) to the novice tutorial. It should state that the goal of the CWL User Guide is to be reference material, for those with some CWL experience.

It might be useful to distinguish between reference material & user guide. If you look at existing reference guides (or manuals), they are normally quite comprehensive, having the same information from a specification, but in a more structured way (not directed to implementaters, but for users/developers?).

The MDN docs has some JS Guides and also Reference material. But their best resource for JS developers is definitely the JS Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

Every entry in the JS reference contains the same structured information, of what part of the specification is being talked about, which version of the specification contains that feature, the valid values, good examples, short description, and normally a widget to try the JS code.

For a standard with specification & implementations, I'd expect a similar reference material, where it doesn't guide the user so much over concepts, but rather gives something that I can reference to when I'm writing a CWL workflow. But I think our User Guide is less structured, having more text to describe the concepts, links between sections, code examples, notes about usage, etc.

For example, if I have a problem with an optional array input field, I'd look at the reference of array inputs, where I'd expect to see the what's valid/invalid, and whether my CWL version supports it (and if I opened the reference of array outputs, I'd expect a page with identical structure, but with information about array outputs). On the other hand, if I had no idea about optional array input field, then I would prefer a more detailed explanation of array inputs, why they are needed, where they are used, how they are used, etc. which is normally present in a user guide.

Besides MDN, Cylc documentation also has a User Guide where readers are guided through tasks like writing workflows, tasks, removing workflows, etc.. And another Reference material for Architecture, the Cylc API, valid environment variables, configuration, etc. (more developer & advanced-user oriented).

I think Diátaxis does a good job separating docs for Tutorials/How-to guides/Reference/& Explanation.