On Tue, May 12, 2009 at 12:43:21PM +0300, Peter Pentchev wrote: [snip] > Well... I think I should rather let others answer that - I'm not > a DD, not applied even to DM yet (though I intend to do both soon), > just a random volunteer who tries to help Debian every once in > a while with a package or fifteen :) So maybe someone more > authoritative could chime in here and give us an official opinion > if needed :) Just one final point now, and I'm shutting up, I promise :) This is something I simply forgot to write in my previous e-mail, and it was *the main reason* I started writing it! It is, by all means, my largest pet peeve for the past more than twelve years, ever since I started writing documentation for my first small programs and then I had three different coworkers come to me with "simple little questions" that were already answered in the docs. The main reason - I *almost* want to say "the only reason" - for anybody, ever, to write documentation for any project is to lighten the support burden on the project authors later on. Let's just consider a simple little question that may be answered in two sentences and may be documented in five (e.g. including a section heading). Now, which do you think is easier *for everyone*: 1. The author does not document the question, and in the next year, fifty people ask him the same question in person, via e-mail, ICQ, IRC, or bug reports. Each time he responds with the same two sentences, for a total of fifty sentences for the question, a hundred sentences for the answer, and a hundred minutes time overall. Also, the author is... let's say, somewhat irritated... for having to repeat himself fifty times. Hopefully, he gets irritated enough to document the answer :) 2. The author does document the question. Throughout the next year, fifty people read the question in the docs and do not bother the author, for a total of five sentences for the documented question, and fifty-five minutes time overall (five minutes for the author documenting the question, and fifty minutes for the people answering it). Now, in the second scenario, the author has the time to actually do something else while people find the answer for themselves :) And now, consider the case when the author *has* documented the answer and fifty people *still* come to him with the same question, over and over again, when they could have spent a minute - or, well, sometimes five minutes - to just find the answer in the docs. Shall we say, "the author is somewhat irritated"? :) As I said, I'm shutting up now :) G'luck, Peter -- Peter Pentchev roam@ringlet.net roam@space.bg roam@FreeBSD.org PGP key: http://people.FreeBSD.org/~roam/roam.key.asc Key fingerprint FDBA FD79 C26F 3C51 C95E DF9E ED18 B68D 1619 4553 What would this sentence be like if pi were 3?
Attachment:
pgpgcD7VmVmT3.pgp
Description: PGP signature