DragonFly BSD
DragonFly docs List (threaded) for 2005-07
[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]


From: "Simon 'corecode' Schubert" <corecode@xxxxxxxxxxxx>
Date: Wed, 27 Jul 2005 12:07:11 +0200


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


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

[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]