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

Re: Documentation

From: "Simon 'corecode' Schubert" <corecode@xxxxxxxxxxxx>
Date: Wed, 27 Jul 2005 13:35:26 +0200

Jeroen Ruigrok/asmodai 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.

True, but they show how to do it. Meaning, in case you don't even know that you are supposed to document and how, you won't do it.

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

Never said that. But who should keep the docs updated if programmers commit here and there? It's pretty hard to follow changes then. The programmer has the knowledge on what he changed.

I don't say it should be the programmer who writes the docs, I just say the programmer needs to be responsible for getting docs updated. He can talk to somebody who volunteers to update the docs (in private), and once he found somebody, alright! But no commit & forget (no "somebody will update the docs... I hope... but I don't actually care")

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.

My point is: if it ain't got docs, it won't go in. Sorry, it *has* to be that hard, otherwise you need a shitload of motivated people who just live for running after programmers and update the docs. This will *never* be the case (experience shows)!

With officially authorized, I just want to express that it is somebody whose word ("please commit man page update") has a weight, because he was chosen by the community. Without this "official weight", commiters don't care about his words (experience).

I do what I can, where I can (like I am doing with Joerg right now), when I
can and want.

I don't get your point here.

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

I know, but this is not really complete. I'd prefer to have such docs archived in CVS.


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]