Re: Documentation

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

Jeroen Ruigrok/asmodai wrote:
> > I think we are in desperate need of some documentation guidelines, i.e. 
> > who needs to document what and how.
> Guidelines don't write the documentation.

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.

> > - changes need to be documented in the appropriate man pages and
> > configuration files. If a commit doesn't update the documentation
> > (like it should), the documentation needs to be updated within maximum
> > one week.  A person whom I'll call "docs kicker" is officially
> > authorized to kick committers in the ass if they fail to commit
> > documentation (note that it's *not* the responsiblity of the docs
> > kicker to actually write the docs, just to tell people that they
> > still have to write docs).
> Good programmers do not necessarily make good documentation people.

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.

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")

> And officially authorized...  I dislike these kind of practise.  This
> remains a volunteer project and you can whine all you want but for me it
> will remain on a voluntarily basis, including documentation.  And no amount
> of pressure will make me work harder and that goes for more people.  Sorry,
> I don't see that working at all.

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)!

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

> I do what I can, where I can (like I am doing with Joerg right now), when I
> can and want.

I don't get your point here.

> > - create a src/CHANGES, in which commiters need to record major changes
> > to the system (so no small bugfixes, but for example "Imported OpenSSL
> > 0.9.8, a feature release").  
> This is/has been  recorded on:
> http://wiki.dragonflybsd.org/index.php/DragonFly_Status

I know, but this is not really complete.  I'd prefer to have such docs 
archived in CVS.

cheers
  simon

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