For you Linux programmers out there?

[D. Michael McIntyre]

On Wednesday 05 September 2007, Knapp wrote:
> Anyone that write code can write docs (but maybe not in English).
> Maybe not good ones but they can do it.

They could, but they won't.  Programmers don't want to write docs.  They have 
n hours to play with, and they want to spend them programming, not writing 
docs.  Getting programmers to document their own features, even just that 
much, just add a blurb in the manual about your new feature; even that is 
like pulling teeth.

> but don't we all hate lots of things we do everyday? And would the
> world not be much better, if we all spent half our programming time
> doing docs?

Honestly?  Probably not.  I think the time would be better spent developing 
applications and systems that do what people expect without any explanation.

People don't turn to documentation unless they can't understand something 
without it, and the kind of people who can't understand things without 
documentation are, in my experience, usually not that great at understanding 
when they *have* documentation either.  They're mostly the sort of folks who 
need hands-on training from a personal teacher.

Documentation is useful for teachers to have, I grant you, but with our 
limited resources, I don't agree it's the most effective way to invest 
development hours.  I, for example, have been substantially successful as a 
teacher without any good textbooks.

The other problem, and the biggest problem, is shelf life.  The shelf life of  
Linux text is about six months, and then it's junk.  Writing one takes about 
a year.  How do you reconcile that?

One way would be to cut development down by requiring programmers to spend 
half their time writing, and thereby producing less code less often, giving 
the docs time to catch up.  But users would HATE that.

> program. I was talking about the book in the first place but talking
> about documenting code is also very important.

Anyway, I'm venturing into essay territory again, or memoir territory.  I'd 
better not get wound up, because I've got stuff to do.
-- 
D. Michael McIntyre