For you Linux programmers out there?

[Knapp]

>D. Michael McIntyre: I keep trying to say something here without
running on, and two hours later, I
>don't have anything simple to say on this topic.  If I'm going to write an
>essay about the vagaries of documenting Linux projects, I may as well do it
r>ight, and publish it on a blog or something.  Or better yet, figure out some
>way to get someone to pay me to publish it.  :D
>The jist of it, though, is that it's a crappy and nearly impossible job.

>Criss Miller: It's really difficult to properly document code.  Some
bits leave you
>wondering how on earth someone could not understand the code that you
>just wrote, and those often are the parts that need documenting the
>most.  Coders have a notorious lack on an internal barometer to tell
>them when to doc and when not to doc.  It's not something that saying
>something can fix.


Anyone that write code can write docs (but maybe not in English).
Maybe not good ones but they can do it. If they put the time in to do
it, it will help. Once they have done that it makes it much easier for
the next poor soul to come along and make it better writing.
I see no reason that programmer can not do this. Yes, we all hate it
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?

I think there are 2 types of docs being talked about here. One is the
documentation of code and the other is the book that goes with the
program. I was talking about the book in the first place but talking
about documenting code is also very important.

So that brings me to a question. Have you ever gone back to your code
3 years later that was done in some language that you have for gotten
and tried to figure out what you were doing in the undocumented
obvious code sections? I think that every line or at least every loop
and function should have documentation. Old code is a bear to
understand! Now what about that poor person who comes after you and
just learned that old no longer used language after you retire?

Nether type of doc is fun (at least to me) but both types are a total
must do; if we are to make anything that others will ever use or
update.

Douglas