CLI documentation

[jorgeorpinel]

Based on #5392 (comment)

https://clig.dev/#documentation recommends that

Provide terminal-based documentation. Documentation in the terminal has several nice properties: it’s fast to access, it stays in sync with the specific installed version of the tool, and it works without an internet connection.

Consider providing man pages. man pages, Unix’s original system of documentation, are still in use today, and many users will reflexively check man mycmd as a first step when trying to learn about your tool.

Is this something we should try to introduce? How/who could easily implement and maintain these (perhaps automatically as part of the docs integration process). @iterative/docs could potentially be heavily involved.

[jorgeorpinel]

Cc @skshetry

[skshetry]

Note that this was recently updated. Before it said the following:

Don’t bother with man pages.
We believe that if you’re following these guidelines for help and documentation, you won’t need man pages.
Not enough people use man pages, and they don’t work on Windows.
If your CLI framework and package manager make it easy to output man pages, go for it, but otherwise your time is best spent improving web docs and built-in help text.

Citation: 12 Factor CLI Apps.

If your help text is long, pipe it through a pager.
This is one useful thing that man does for you.
See the advice in the “Output” section below.

I worry that we might end up having two different kinds of docs, as dvc.org moves to more interactive version, with admonitions/notes and additional examples, and manpage have to always remain static and structured.

[iesahin]

The command reference can be converted to man pages easily. Even a script using pandoc should be able to do that. We can also have an epub distribution for the User Guide + Use Cases. Markdown is flexible for these conversions.

Installation script can install man pages, and also dvc cmd --help can show the reference page. This requires a bit more sync between DVC versions and the documentation, though.

[casperdcl]

FYI git <cmd> -h = CLI short help, while git <cmd> --help is identical to man git-<cmd>.

Also I would suggest manpage & https://dvc.org/doc/command-reference should be made automatically in sync?

[iesahin]

Also I would suggest manpage & https://dvc.org/doc/command-reference should be made automatically in sync?

Man pages can be produced from the ref pages. It seems the most straightforward way to me. Maintaining a separate set of man pages isn't a wise time investment I believe.

We may need changes in the command reference to conform to more "manpage-like" content. We are already moving the examples and explanations to UG and UC. Options, their usage, their explanations and a set of quick examples may be enough for the command reference / man.

[casperdcl]

after discussion, potential conclusion:

• probably too much effort to rejig the docs system or automate manpage ↔️ https://dvc.org/doc/command-reference sync
• just because https://dvc.org/doc/command-reference exists, we shouldn't shy away from fleshing out dvc <cmd> --help a little with examples (vis https://github.com/tldr-pages/tldr)

[daavoo]

What about keeping dvc <cmd> -h and https://dvc.org/doc/command-reference in sync by using the former to auto-generate some sections of the later iterative/dvc.org#2770

[iesahin]

Related iterative/dvc.org#2108