Gentoo Archives: gentoo-dev

From: Ciaran McCreesh <ciaran.mccreesh@×××××××××××××.uk>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] Re: [RFC] Features and documentation
Date: Wed, 28 Nov 2007 21:36:31
In Reply to: Re: [gentoo-dev] Re: [RFC] Features and documentation by Donnie Berkholz
1 On Wed, 28 Nov 2007 13:14:05 -0800
2 Donnie Berkholz <dberkholz@g.o> wrote:
3 > Many of the replies keep asking for details -- details that don't
4 > exist. Apply the concept abstractly: things that need to be
5 > documented must have documentation available in the appropriate form
6 > at the time they're committed.
8 Which still doesn't bring anything discussable or implementable. A
9 large part of why many things aren't documented is that people have
10 very different ideas about what level of documentation is required;
11 this does nothing to affect that.
13 > What remains unclear about this principle?
15 It's entirely nebulous and has nothing that can be discussed or agreed
16 upon, beyond giving people a feel good "ooh, yes, we should do this"
17 with no practical purpose. It has an unpleasant smell of something a
18 Dilbert-esque manager would introduce after having read a "Project
19 Management for Dummies" book full of slogans and generalities.
21 So, if you want to take this somewhere useful:
23 * Decide what the scope of a change is. Are we talking anything
24 user-visible? Anything substantially user-visible? Anything requiring
25 user action? Anything developer-visible? Anything requiring developer
26 action? Anything visible to small numbers of developers working in a
27 specific area?
29 * Decide what the appropriate level of documentation is.
31 * Discuss how you're going to get documentation of a sufficiently high
32 quality. Most developers aren't going to go out and spend several months
33 studying technical writing...
35 * Decide whether it's worth putting the limited available writing
36 resources into developer documentation that will only be read by a few
37 hundred people, rather than putting more focus into user documentation
38 that will be read by pretty much everyone.
40 You know... Practical things, rather than things that make you feel
41 good but go nowhere.
43 --
44 Ciaran McCreesh


File name MIME type
signature.asc application/pgp-signature


Subject Author
Re: [gentoo-dev] Re: [RFC] Features and documentation Donnie Berkholz <dberkholz@g.o>
[gentoo-dev] Re: [RFC] Features and documentation Duncan <1i5t5.duncan@×××.net>