21 Sep
2023
21 Sep
'23
5:30 a.m.
At 2023-09-20T20:06:27-0700, Adam Thornton wrote:
That's it, isn't it? Man pages are great if
you a) already know the
name of the program you want (c'mon, apropos/man -k have never really
worked that well),
I think that's less a technology problem than a human problem. People
need to write the summary descriptions of a man page--that would be
.SH Name
this part \- right here
in a way that helps people find it.
Sure, you could use AI <cough> to scan the full texts of pages to try to
infer keywords, but I don't see that putting natural intelligence out of
business quite yet.
Man page authors labor under all kinds of crazy delusions about what can
go into the "Name" section. Some people seem to think there's a length
limit. Some seem to think that the summary description has to fit on
one _input line_, as if filling is disabled when it's read.
But they aren't great for either exploration or
discoverability.
I got positive feedback on the groff development list regarding
precisely these points when (1) revising its ~60 man pages to give them
more helpful summary descriptions and (2) compiling them into a
navigable PDF.
https://www.gnu.org/software/groff/manual/groff-man-pages.pdf
Say what you will about VMS, its HELP functionality
makes it much
easier to go from "I want to do X" to "And here's a sequence of
commands that will do X" when you don't already have a good mental
model of what's on the system.
My experience with VMS is far too limited (and 30 years out of date) to
offer any comparison here, but I do agree that man pages are frequently
unhelpful when it comes to synthesis of the components they document.
Taking the "Examples" section more seriously might help with this.
At the same time I get that it's really tempting to punt. "If it's not
documenting this discrete element of the system," people want to say,
"it doesn't belong in the man page". I sympathize with that perspective
only insofar as the people who say this then proceed to offer some
alternative form of documentation that does. If they don't, then I
suspect this professed piety about modular design to be a mask for
unwillingness to do work that needs doing.
Regards,
Branden