Documentation

[Simon 'corecode' Schubert]

Hey,

I think we are in desperate need of some documentation guidelines, i.e. 
who needs to document what and how.  We've been lazy in documenting 
changes to our system (including myself), but we shouldn't give up this 
big pro of BSD - the excellent 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:

- 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).
- 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 will make it much more easy to track
  changes for release notes, for example.  This file is being emptied
  after every release, meaning it just contains changes since the last
  release.
- We should have several volunteers who actually *know* the handbook and
  keep it in sync with reality.  Of course committers are required to
  clarify sections if the handbook volunteers don't exactly know how
  things changed.
This will us help to at least keep the status quo.  If this proves to 
work, we would have to form some kind of taskforce which will update 
docs so that they match changes we missed to update until now.

I'm willing to volunteer for the docs kicker position and commit docs 
changes submitted.

What do you think?

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