From: Clem Cole <clemc@ccc.com>
To: Larry McVoy <lm@mcvoy.com>
Cc: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>,
TUHS main list <tuhs@tuhs.org>
Subject: [TUHS] Re: On Bloat and the Idea of Small Specialized Tools
Date: Sat, 18 May 2024 14:52:05 -0400 [thread overview]
Message-ID: <CAC20D2NbHEdxKU6HA_ZQWYmc-HGhLE+F4e8XFoWePToRBP4-9Q@mail.gmail.com> (raw)
In-Reply-To: <20240518181825.GT9216@mcvoy.com>
[-- Attachment #1: Type: text/plain, Size: 3144 bytes --]
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*."
ᐧ
[-- Attachment #2: Type: text/html, Size: 6731 bytes --]
next prev parent reply other threads:[~2024-05-18 18:52 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-18 18:07 Douglas McIlroy
2024-05-18 18:13 ` Brantley Coile
2024-05-18 18:18 ` Larry McVoy
2024-05-18 18:52 ` Clem Cole [this message]
2024-05-18 19:19 ` Luther Johnson
2024-05-18 20:12 ` segaloco via TUHS
2024-05-18 19:32 ` Stuff Received
2024-05-18 18:22 ` Ralph Corderoy
2024-05-19 8:58 ` [TUHS] The 'usage: ...' message. (Was: On Bloat...) Ralph Corderoy
2024-05-18 18:31 ` [TUHS] Re: On Bloat and the Idea of Small Specialized Tools Peter Weinberger (温博格) via TUHS
2024-05-18 20:33 ` Steffen Nurpmeso
2024-05-19 8:39 ` Marc Rochkind
2024-05-20 6:07 ` Adam Thornton
2024-05-20 15:43 ` [TUHS] Documentation (was On Bloat and the Idea of Small Specialized Tools) Paul Winalski
2024-05-20 16:37 ` [TUHS] " Andrew Hume
2024-05-20 18:38 ` Yeechang Lee
2024-05-20 19:27 ` Phil Budne
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAC20D2NbHEdxKU6HA_ZQWYmc-HGhLE+F4e8XFoWePToRBP4-9Q@mail.gmail.com \
--to=clemc@ccc.com \
--cc=douglas.mcilroy@dartmouth.edu \
--cc=lm@mcvoy.com \
--cc=tuhs@tuhs.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).