Re: Quality of source material from Development

[Sandy Harris <sandy -at- storm -dot- ca>]

Chris Gooch wrote:

> I'd just like to wonder where this idea that software engineers,
> uniquely amongst the scientific and engineering community,
> are such dunderheads that they can't put a sentence together.

Here is a post of mine to the local Linux user group mailing list a
few months back that includes comment on this:

> 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.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  And it's
affordable.  Join our alomst 10,000 published authors today.
http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.