19 May
2024
19 May
'24
1:19 a.m.
Complexity is entropy. It occurs naturally in all human endeavor. It
takes work to keep things small, orderly, and rational. But there is
also a point where although a tool may be perfect in its conception and
execution, from its own perspective, it is not as useful as a slightly
more disorderly version that does what people want it to do. "Well they
shouldn't want that !" is a common response. Then people write scripts
to do for themselves what the tool doesn't do. Which might be right, but
it might lead to a whole bunch of similar scripts to do the same thing,
just a little differently And that's when we discover that it would have
been better to have it in the one tool in the first place.
So it's a back and forth, trial and error process. Eventually new
balances get struck, and people of like minds and tastes find a new
center, like Plan 9, or other things.
Myself, I do tend to like tools that are smaller and more single-minded
in their function (and that makes it possible to have documentation that
is clearer and more concise), but as an example, sometimes I want the
"-u" switch on diff, to make a patch, sometimes I don't, the default
display is better for a quick review (but I think or expect that the
essential diff engine is being shared). It's all a matter of judgment,
but you can't apply good judgment until you have the experience gained
from trying several alternatives. So things will get bloated up, and
then they will need to be pruned and re-engineered, but hopefully we
don't throw out the most helpful exceptions to the rule just because
they don't fit with some sort of consistency aesthetic.
On 05/18/2024 11:52 AM, Clem Cole wrote:
On Sat, May 18, 2024 at 2:18 PM Larry McVoy <lm(a)mcvoy.com
<mailto:lm@mcvoy.com>> wrote:
But I'm ok with a terse man page with a SEE ALSO thatpoints 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 howto 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 builtmanual
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,
basicreferenceand 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/."
ᐧ