DragonFly kernel List (threaded) for 2005-07
-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:
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...