Documentation

[Simon 'corecode' Schubert]

Jeroen Ruigrok/asmodai wrote:
Never said that.  But who should keep the docs updated if programmers 
commit here and there?  It's pretty hard to follow changes then.  The 
programmer has the knowledge on what he changed.
Technical writers.  They are the ones that will harass the programmer with
relevant questions.
Iff they exist.

I don't say it should be the programmer who writes the docs, I just say 
the programmer needs to be responsible for getting docs updated.  He can 
talk to somebody who volunteers to update the docs (in private), and 
once he found somebody, alright!  But no commit & forget (no "somebody 
will update the docs... I hope... but I don't actually care")
Given the fact that the programmer is worth his money for the programming
work he does I'd rather have a programmer program and not worry too much
about the documentation and leave that to the people worth their money for
documentation.
We neither pay programmers nor documentation guys.  And obviously there 
are less people interested in documentation than in new features.

Only major request would be verbose log messages of commits that clearly
describe what the commit is all about.
Now that's user friendly: "Huh? why doesn't this work as adviertised in 
the man page?  Oh, I'll just have a quick look at the CVS log messages..."

My point is: if it ain't got docs, it won't go in.  Sorry, it *has* to 
be that hard, otherwise you need a shitload of motivated people who just 
live for running after programmers and update the docs.  This will 
*never* be the case (experience shows)!
So you effectively want to have a policy that would ban good code solely on
the pretext of not being accompanied by good documentation?
Yes.  If it's not guaranteed that there will be documentation coming, 
the code shouldn't go in.

With officially authorized, I just want to express that it is somebody 
whose word ("please commit man page update") has a weight, because he 
was chosen by the community.  Without this "official weight", commiters 
don't care about his words (experience).
Even if you had "official weight" I still could not care more or less.  My
spare time is my own to spend as I see fit.  Of course I can take it into
consideration, but given the average open source person's todo list...
It's not about me.  I just volunteered.  I'd be happy if somebody else 
would find the time to do this job.

Sorry if it sounds harsh, but spare time not copious and typically a
person's spare time is filled with the stuff they like to work on.
Sorry if it sounds harsh, but if you refuse to document changes and hope 
that somebody else will do that for you instead, sometime, you better go 
somewhere else and spend your free time changing that code without 
documenting.  I heard that this was en-vogue in linuxland, but I don't 
really know.

[wiki]
I know, but this is not really complete.  I'd prefer to have such docs 
archived in CVS.
It already is *points to commit messages*.
Oh you volunteer to digest release notes out of six months of commit 
messages?  Way cool!

--
Serve - BSD     +++  RENT this banner advert  +++    ASCII Ribbon   /"\
Work - Mac      +++  space for low $$$ NOW!1  +++      Campaign     \ /
Party Enjoy Relax   |   http://dragonflybsd.org      Against  HTML   \
Dude 2c 2 the max   !   http://golden-apple.biz       Mail + News   / \