Documentation

[Jeroen Ruigrok/asmodai]

-On [20050727 13:36], Simon 'corecode' Schubert (corecode at xxxxxxxxxxxx) wrote:
>Jeroen Ruigrok/asmodai wrote:
>True, but they show how to do it. Meaning, in case you don't even know 
>that you are supposed to document and how, you won't do it.

Even if it is documentated how to document it is no guarantee. ;)

>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.

>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.

Only major request would be verbose log messages of commits that clearly
describe what the commit is all about.

>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?

>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...

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.

[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*.

But that's just my take on it, based on a bunch of years (6 or so) of
messing with projects and open source in particular.

-- 
Jeroen Ruigrok van der Werven <asmodai(at)wxs.nl> / asmodai / kita no mono
Free Tibet! http://www.savetibet.org/ | http://ashemedai.deviantart.com/
http://www.tendra.org/   | http://www.in-nomine.org/
I dream of Love as Time runs through my hand...