DragonFly kernel List (threaded) for 2005-07
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.
Good programmers do not necessarily make good documentation people.
- 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).
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 / \