On Tue, 4 Dec 2018 15:16:50 -0500
Peter Schaffter <pe...@schaffter.ca> wrote:
> When I analyze my initial impression of manpages, I see that it
> was a clash between approaching computing from the humanities,
> as a non-programming user, versus approaching computing from the
> sciences, as a programmer.
I don't think that's quite right, Peter. I suggest to you that's the
difference between a user guide and a reference manual. We need both,
always have, and the humanities have nothing to do with it, except
insofar as they teach clear exposition.
The CSRG reports were written by computer scientists. They describe,
for instance, troff, tbl, pic, and the ms macros in a conversational,
entertaining way.
.NH Care and Feeding of Department Heads
produces
1. Care and Feeding of Department Heads
They do what no man page should: explain how the tool can be used to
solve a problem. They introduce the tool from a blank slate, making it
possible for the newcomer to absorb what it's about and give him some
insight into the tool's "philosophy".
I recently had cause to read the documentation for the Python LDAP
library. It might be the worst example of the disease you cite, the
need to know everything before you can understand any of it. The
library cries out for a user guide: a narrative explanation of how to
use it and what all the components do. The library is nearly impossible
to understand because no such document exists, not even something that
explains the order in which the functions should be called.
The read/refer dichotomy never completely goes away. Even the standard
manpage embeds how in the what. The list of options, for example, puts
the option on the left and the explanation on the right. But who reads
that list wondering what each option does? Don't we more commmonly
scan the explanations for the option we want, right to left, as it
were?
You'd have a hard time convincing me that MOM is more complex than
troff itself, or that groff_mom(7) would be longer or harder to
organize than groff(7). The very fact that your HTML documentation is
frequently viewed is proof, actually, that a reference manual is
needed. That's not to say you should write it or even want to see it
written, only that a convenient reference is ... convenient.
--jkl
