For you Linux programmers out there?
D. Michael McIntyre
michael.mcintyre at rosegardenmusic.com
Wed Sep 5 23:54:27 UTC 2007
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
More information about the kubuntu-users