On Thu, Sep 19, 2019 at 2:11 PM Norman Wilson <norman@oclsc.org> wrote:

> Manual entries, as printed by man and once upon a time in
> the Programmers' Manual Volume 1, should be concise references.
> They are not a place for tutorials or long-winded descriptions
> or even long lists of hundreds of options (let alone descriptions
> of why the developer thinks this is the neatest thing since
> sliced bread and what bread he had in his sandwiches that day).
>
> For many programs, one or two pages of concise reference is
> all the documentation that's needed; no one needs a ten-page
> tutorial on how to use cat or rm or ls, for example.  But some
> programs really do deserve a longer treatment, either a tutorial
> or an extended reference with more detail or both.  Those belong
> in separate documents, and are why the Programmers' Manual had
> a second volume.
>
> Nowadays people think nothing of writing 68-page-long manual
> entries (real example from something I'm working with right now)
> that are long, chatty lists of options or configuration-file
> directives with tutorial information interspersed.  The result
> makes the developer feel good--look at all the documentation
> I've written!!--but it's useless for someone trying to figure
> out how to write a configuration file for the first time, and
> not so great even for someone trying to edit an existing one.
>
> Even the Research system didn't always get this right; some
> manual entries ran on and on and on when what was really
> needed was a concise list of something and a longer accompanying
> document.  (The Tenth Edition manual was much better about
> that, mostly because of all the work Doug put in.  I doubt
> there has ever been a better editor for technical text than
> Doug.)  But it's far worse now in most systems, because
> there's rarely any editor at all; the manuals are just an
> accreted clump.
>
> And that's a shame, though I have no suggestions on how
> to fix it.
>
> +1