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 15:01:48 +0200

Jeroen Ruigrok/asmodai wrote:
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.
Technical writers.  They are the ones that will harass the programmer with
relevant questions.

Iff they exist.


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")
Given the fact that the programmer is worth his money for the programming
work he does I'd rather have a programmer program and not worry too much
about the documentation and leave that to the people worth their money for
documentation.

We neither pay programmers nor documentation guys. And obviously there are less people interested in documentation than in new features.


Only major request would be verbose log messages of commits that clearly
describe what the commit is all about.

Now that's user friendly: "Huh? why doesn't this work as adviertised in the man page? Oh, I'll just have a quick look at the CVS log messages..."


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)!
So you effectively want to have a policy that would ban good code solely on
the pretext of not being accompanied by good documentation?

Yes. If it's not guaranteed that there will be documentation coming, the code shouldn't go in.


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).
Even if you had "official weight" I still could not care more or less.  My
spare time is my own to spend as I see fit.  Of course I can take it into
consideration, but given the average open source person's todo list...

It's not about me. I just volunteered. I'd be happy if somebody else would find the time to do this job.


Sorry if it sounds harsh, but spare time not copious and typically a
person's spare time is filled with the stuff they like to work on.

Sorry if it sounds harsh, but if you refuse to document changes and hope that somebody else will do that for you instead, sometime, you better go somewhere else and spend your free time changing that code without documenting. I heard that this was en-vogue in linuxland, but I don't really know.


[wiki]
I know, but this is not really complete. I'd prefer to have such docs archived in CVS.
It already is *points to commit messages*.

Oh you volunteer to digest release notes out of six months of commit messages? Way cool!


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