Simon 'corecode' Schubert
corecode at fs.ei.tum.de
Wed Jul 27 03:08:20 PDT 2005
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
- 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
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
What do you think?
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 / \
More information about the Docs