[setrofim_]

The issue isn't just the lack of EXAMPLES, but also with how man pages tend to be structured. They tend to be very "encyclopedic". There is a set ordering for sections, with a lot of them very verbose, and examples, when present, near the end. Options are often listed in alphabetic order, which doesn't usually correspond to how often they are used or useful.

Man pages are OK when you're first learning how to use something; but if you're already familiar with a command and just need to remind yourself of a the specific sequence of options to achieve a desired result, they're not the most convenient.

I think it's useful to have a tool that fulfills the latter purpose without worrying about the former.

[JdeBP]

Microsoft documentation was mentioned earlier in this discussion. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things.

The FreeBSD, TrueOS, and related worlds put the "using" doco into what are often called "handbooks" or "guides".

* NetBSD Guide: https://netbsd.org/docs/guide/en/

* FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html

* DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/

* TrueOS User Guide: https://www.trueos.org/handbook/trueos.html

* PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/)

Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example:

* http://upstart.ubuntu.com/cookbook/

The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide:

* https://en.wikibooks.org/wiki/Guide_to_Unix

* https://en.wikibooks.org/wiki/Linux_Guide

If you want examples and doco that works from the basis of what you usually want to do, then these handbooks and guides are the places to go, not reference manuals.

[teddyh]

Whenever the discussion comes up about man pages and how documentation should be organized, I like to quote this section from the GNU coding standards about how Info documentation is structured:

----

Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.

Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented--but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives.

[…]

In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. […]

That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text.

https://www.gnu.org/prep/standards/standards.html#GNU-Manual...