Re: Documentation

["Simon 'corecode' Schubert" <corecode@xxxxxxxxxxxx>]

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   / \