Re: Slashdot reply (draft 0.1)

[Sandy Harris <sandy@storm.ca>]

jdd wrote:
> 
> On ven, 11 fév 2000, Guylhem Aznar à écrit

> >I think programmers should try to document their own apps (quoting a
> >slashdotter again : "If I can't clearly and concisely write what I'm
> >doing then my algorithm just isn't very good")
> 
> this is wrong.

I think it is true for some parts, not for others.

> Writing programs and writing documentation are two completely
> different works. Need only read man pages to see this, who can
> use a program only with man page -mostly without any example...

So let the programmers write the man pages. Take it from there.
This sometimes includes fixing botched man pages, but not often
in my experience.
 
Dijkstra wrote in his classic "truths that might hurt" paper:
http://serv1.imm.dtu.dk/documents/users/aaa/hurtingtruths.html

" Besides a mathematical inclination, an exceptionally good mastery
" of one's native tongue is the most vital asset of a competent
" programmer. 

My experience is that the really good programmers can explain what
they're doing, at least to me if not to someone with less background
or persistence. 

Also, the good ones do routinely write some things well. Specs, man
pages. Sometimes HowTos: Rusty Russell's ipchains stuff comes to mind.
Eric Raymond and Alan Cox have both written some pretty good essays.
Quite a few Usenix papers are well-written. 

Of course, some programmer-written docs are absolutely awful too.

> ideally any programmer should have with him a documentation writer...

Yes, for many reasons. Programmers have other things to do and division
of labour is a Good Thing(TM). Docs may be needed in languages the
programmer is not entirely fluent in. A good tech writer can produce
docs for audiences the programmer does not write well for.

Even the best writer needs an editor. We do that for programmer-written
docs. Then there's indexing, consistency checking, adding footnotes and
glossary and cross-references and examples and illustrations and ...

Even when programmers provide big chumks of the content, there's still
plenty of work for us.


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org