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