On Sat, May 18, 2024 at 2:18 PM Larry McVoy <lm@mcvoy.com> wrote:

> But I'm ok with a terse man page with a SEE ALSO that points to a user
> guide.
>
Only if the SEE ALSO has more complete and relevant information -
otherwise, it degrades to VMS's famous "see figure 1" SPR.

>
> Docs should be helpful.
>
And easy to extract information.

The issue to be comes back to the type of information each document is
designed to give. I believe there at least three types of docs:

   1. Full manuals explain how something is built and it it used.  It helps
   to have theory/principles of operations behind it and enough detail when
   done, you can understand why and how to use it.
   2. Tutorials are excellent for someone trying to learn a new tool.  Less
   theory - and more -- examples, showing off the features and how to do
   something.
   3. References pages - need to be quick look-ups to remind someone how to
   use something - particularly for tools you don't use every
   day/generally don't memorize.


There are at least two more: an academic paper which might be looked at as
a start of #1 and full books which take #1 to even more details.  Some
academic papers indeed are fine manuals, and I can also argue the "manual"
for some tools like awk/sed or, for that matter, yacc(1) are full
books. But the idea is the >>complete<< review here.

Tutorials and reference pages are supposed to easy helpful things -- but
often miss the mark for the audience.  To me, the problem is the wrong type
of information is put in each one and, more importantly, people's
expectations from the document.  I love properly built manual pages - I
detest things like the VMS/TOPS help command or gnu info pages. What I
really hate is when there is no manual, but they tell you see the HELP
command -- but which command or "subtopic" -- Yikes.  The traditional
man system is simple quick reminders, basic reference and I can move on.
For instance, I needed to remember which C library has the definition these
days for some set of functions and what are its error return codes -- man 3
functions, I'm done.

Tutorials are funny.  For some people, what they want to learn the ideas
behind a tool.  Typically, I don't need that as much as how this toll does
some function.   For instance, Apple is forcing me the learn lldb because
the traditional debuggers derived from UCB's DBX are not there.   It's
similar to different.  The man page is useful only for the command lines
switches.   It turns out the commands are all really long, but they have
abbreviations and can be aliases.  I found references to this in an lldb
tutorial - but the tutorial is written to teach people more how to use a
debugger to debug there code, and less how this debugger maps into the
traditional functions.  Hey I would like to find an cheat sheet or a set of
aliases that map DBX/GDB into it -- but so far I've found nothing.

So Larry -- I agree with you ... "*Docs should be helpful*," but I fear
saying like that is a bit like the Faber College Motto/Founder's
Quote: "*Knowledge
is good*."



ᐧ