Re: Documentation

[Jeroen Ruigrok/asmodai <asmodai@xxxxxxxxxxxxx>]

-On [20050727 12:16], Simon 'corecode' Schubert (corecode@xxxxxxxxxxxx) 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.

>Code quality is important, but documentation is equally important, at 
>least that's what I think.  This is why I'd like to propose some 
>guidelines for committers and submitters:

I do not disagree with the notion documentation is important.

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

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.
I do what I can, where I can (like I am doing with Joerg right now), when I
can and want.

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

-- 
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/
The intuitive mind is a sacred gift and the rational mind is a faithful
servant. We have created a society that honors the servant and has
forgotten the gift...