documentation and the unix way, Re: [oclug] documentation rant

[Sandy Harris]

Francis Pinteric wrote:

> Talking about the unix way ...
> 
> It is a matter of history that there has always been a huge dislike
> by *real* programmers of anything to do with bureaucarcy. In the
> so-called "good old days" we were all mostly anarchists with a few
> communists sprinkled in for good measure.

Perhaps, but man pages have always been part of the "Unix way(TM)".
Arguably, the worst mistake the Open Source movement has made was
FSF deprecating man pages in favour of info.

Look at Kernighan and Plauger "Software Tools", the book on portable
(in Ratfor, a Fortran pre-processor for a C-like language because C was
not widespread and Fortran was) Unix-like tools, mid 70s, or "Software
Tools in Pascal" (written after Kernighan spent a sabbatical at Berkeley,
late 70s?) Every coding example starts with the man page.
 
> Adding comments to code and then documenting it was seen as a
> conspiracy to stifle creativity and supplant conformity and
> regimentation. *Real* programmers don't do comments and certainly
> don't document. 

I mostly work as a technical writer. I've certainly encountered
programmers who failed to document their code or did an appalling job
when they tried, and I don't expect to be unemployed anytime soon.

That said, my experience is directly contrary to the "real programmers
don't document" school of thought. The really good ones do, and what
they write is clear and usually well-written.

Of course it may be unintelligible without a lot of background information
and may be utterly unmatched to user needs. Large parts of it may be on the
wrong level of abstraction for many readers, or focused on program features
rather than user tasks, or using terminology that's meaningless to users.
That's why you still need tech writers. 

But I do not believe that anyone who cannot write a clear summary of
what his code does -- readable by his peers if perhaps no-one else -- 
understands whatever problem he's solving well enough I'll trust his
solution. 

Methinks Djikstra was correct in his "Truths that Might Hurt" paper
(Fortran is an infantile disorder, teaching COBOL should be considered
a criminal offense, ...) when he claimed that, apart from mathematical
ability the surest mark of a good programmer is the ability to write
clearly in his native language.

For an example, see the FreeS/WAN docs. The developers write the man
pages:
http://www.freeswan.org/freeswan_trees/freeswan-1.9/doc/manpages.html
and some design docs:
http://www.freeswan.org/freeswan_trees/freeswan-1.9/doc/intro.html#applied
and I write everything else:
http://www.freeswan.org/freeswan_trees/freeswan-1.9/doc/index.html

This works out moderately well. Most of the problems that come up involve
either me not keeping up with development or users failing to RTFM.