[documentation] Improve the documentation for each command on the cmd-line text, and on our website
This is feedback from DE users asked via mattermost. User reported "the explanations are not very helpful to me, but maybe other people with more context do know what they mean".
We have a general description of the most used commands on the Getting Started page.
Then, the description of other commands are spread in other pages, like "Create new experiment" that describes expid
and also the usage/options.
But other commands do not follow the same pattern, .like updatedescrip
.
There's also a bug in the image above, as the example is not including the command, only autosubmit <EXPID>
. At least the --help
information for that command is very clear, but the help messages are not standardized across commands. We need to be clear, and give enough context for new users to understand the commands reading the docs and/or terminal --help
messages.
Nextflow contains a complete section about the Command line interface (CLI), https://nextflow.io/docs/latest/cli.html.
For each ecFlow client option, there is a page that matches what's displayed on the terminal, https://ecflow.readthedocs.io/en/latest/client_api/index.html. This page is really amazing, click on each command, and you are redirected to a page with complete information about the command. For example, the ecflow client abort command page is exactly the same displayed on command-line, and it's exactly what they have in the code (i.e. this page https://github.com/ecmwf/ecflow/blob/56731b40278cc0105165aba090e0dfcbd25f3878/docs/client_api/api/abort.rst was produced using the code from https://github.com/ecmwf/ecflow/blob/de1c71bc715645ce40da2f189f37fdcde21afe99/libs/base/src/ecflow/base/cts/task/AbortCmd.cpp#L92 -- ).