[TUHS] earliest Unix roff
clemc at ccc.com
Fri Sep 20 04:37:05 AEST 2019
On Thu, Sep 19, 2019 at 2:11 PM Norman Wilson <norman at 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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the TUHS