Gentoo Archives: gentoo-dev

From: Duncan <1i5t5.duncan@×××.net>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Re: [RFC] Features and documentation
Date: Thu, 29 Nov 2007 05:08:19
In Reply to: Re: [gentoo-dev] Re: [RFC] Features and documentation by Ciaran McCreesh
1 Ciaran McCreesh <ciaran.mccreesh@×××××××××××××.uk> posted
2 20071128213319.09f73e89@×××××××××××××.uk, excerpted below, on Wed, 28 Nov
3 2007 21:33:19 +0000:
5 > On Wed, 28 Nov 2007 13:14:05 -0800
6 > Donnie Berkholz <dberkholz@g.o> wrote:
7 >> Many of the replies keep asking for details -- details that don't
8 >> exist. Apply the concept abstractly: things that need to be documented
9 >> must have documentation available in the appropriate form at the time
10 >> they're committed.
12 OK, I can accept that details don't (yet) exist, but that's why the
13 discussion. =8^) Hopefully it'll flesh out some of these details.
15 > A large part of why many things aren't documented is that people have
16 > very different ideas about what level of documentation is required;
17 > this does nothing to affect that.
19 Agreed. The current discussion on the metadata changes is a prime
20 example. Obviously, there was disagreement on the level of documentation
21 needed. A nebulous "document before change" policy can't help in such
22 cases, as one side or the other's going to get very frustrated, either by
23 "extreme" enforcement (seen by the one side), or lack of enforcement
24 (seen by the other). The /best/ that could come out of such would be
25 that it's as if there were no policy at all. The worst... people leaving
26 because of "unfair" enforcement of a policy so nebulous they never saw
27 the action coming, or OTOH, because Gentoo refuses to enforce its own
28 policies.
30 >> What remains unclear about this principle?
31 >
32 > It has an unpleasant smell of something a Dilbert-esque manager would
33 > introduce after having read a "Project Management for Dummies" book
34 > full of slogans and generalities.
36 Leave it to ciarnm to be so direct, amusing tho it is, but that pretty
37 much nails it. I've seen it said by some that Gentoo's no longer "fun".
38 I disagree but honestly, ask yourself if there's a better way to ruin the
39 fun remaining than by instituting policies so nebulous they simply /beg/
40 for argument over their application. The idea sounds so nice, something
41 everybody should be able to agree to in principle, but that's precisely
42 the problem, there's no specifics, so no practical way to tell where or
43 how it applies, or what changes (if any) it would bring. Pardon my
44 saying so but at least in the US, it's the season of politics, and we're
45 seeing a lot of this vague "big stroke" pie in the sky painting right
46 now. Unlike most of those, there's a chance with this one to get it
47 nailed down to the point it's actually practical.
49 (Bullet point suggestions for tightening down the spec to something
50 "workable" omitted for brevity. Ciarnm put them well enough.)
52 > You know... Practical things, rather than things that make you feel
53 > good but go nowhere.
55 =8^)
57 As an alternative or adjunct to Ciaran's suggestions, perhaps this will
58 be easier, tho not immediately as complete. Self-evidently if you are
59 making the proposal, you believe there's a need for it and that it would
60 change the outcome in one or more events in the recent and possibly less
61 recent past. What about listing them, and how you see your proposal
62 changing the outcome thereof. At least that would give us some concrete
63 examples to apply the policy to in our heads as we discuss it. As I
64 said, it's not as complete as the thorough evaluation Ciaranm proposed,
65 but one has to start somewhere, and this would be one way to do it.
66 OTOH, it's also getting very specific about perhaps sensitive events,
67 while Ciaran's proposal would avoid singling out such events and
68 therefore people by name, thus having the advantage there as well as in
69 ultimate wholeness, once it's done.
71 --
72 Duncan - List replies preferred. No HTML msgs.
73 "Every nonfree program has a lord, a master --
74 and if you use the program, he is your master." Richard Stallman
76 --
77 gentoo-dev@g.o mailing list


Subject Author
Re: [gentoo-dev] Re: [RFC] Features and documentation Donnie Berkholz <dberkholz@g.o>