Re: [TUHS] earliest Unix roff

[Jon Steinhart <jon@fourwinds.com>]

Clem Cole writes:
>
> 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

This is sort of my late in life mission.  Here's a description of a session
that I've proposed for an upcoming conference.

	Once upon a time there was Budweiser. Then, along came craft beer
	which started a movement. Now, one can find a whole range of
	offerings from craft cheese to artisanal baking soda. Hard to find
	is craft programming. What’s called "programming technology" today
	seems to be the art of minimizing the damage that can be done by
	monkeys at keyboards. Since we can no longer purchase even a
	toothpick that doesn’t contain a processor and a blue LED, we depend
	on code. How can we revive the art of programming? How do we foster
	the creation of good code instead of spending energy minimizing the
	damage that can be done by bad code? Our lives depend on it.

My two cents is that craft programmers know how to write good documentation.
Probably one of the things that made BTL so wonderful was the breadth of
knowledge that people had.  Ken was recently telling me about Lee McMahon who
was a classically trained monk in addition to writing qsort for V3.