[gentoo-dev] Re: [RFC] Features and documentation

[Duncan <1i5t5.duncan@cox.net>]

Ciaran McCreesh <ciaran.mccreesh@blueyonder.co.uk> posted
20071128213319.09f73e89@blueyonder.co.uk, excerpted below, on  Wed, 28 Nov
2007 21:33:19 +0000:

> On Wed, 28 Nov 2007 13:14:05 -0800
> Donnie Berkholz <dberkholz@gentoo.org> wrote:
>> Many of the replies keep asking for details -- details that don't
>> exist. Apply the concept abstractly: things that need to be documented
>> must have documentation available in the appropriate form at the time
>> they're committed.

OK, I can accept that details don't (yet) exist, but that's why the 
discussion.  =8^)  Hopefully it'll flesh out some of these details.

> A large part of why many things aren't documented is that people have
> very different ideas about what level of documentation is required;
> this does nothing to affect that.

Agreed.  The current discussion on the metadata changes is a prime 
example.  Obviously, there was disagreement on the level of documentation 
needed.  A nebulous "document before change" policy can't help in such 
cases, as one side or the other's going to get very frustrated, either by 
"extreme" enforcement (seen by the one side), or lack of enforcement 
(seen by the other).  The /best/ that could come out of such would be 
that it's as if there were no policy at all.  The worst... people leaving 
because of "unfair" enforcement of a policy so nebulous they never saw 
the action coming, or OTOH, because Gentoo refuses to enforce its own 
policies.

>> What remains unclear about this principle?
> 
> It has an unpleasant smell of something a Dilbert-esque manager would
> introduce after having read a "Project Management for Dummies" book
> full of slogans and generalities.

Leave it to ciarnm to be so direct, amusing tho it is, but that pretty 
much nails it.  I've seen it said by some that Gentoo's no longer "fun".  
I disagree but honestly, ask yourself if there's a better way to ruin the 
fun remaining than by instituting policies so nebulous they simply /beg/ 
for argument over their application.  The idea sounds so nice, something 
everybody should be able to agree to in principle, but that's precisely 
the problem, there's no specifics, so no practical way to tell where or 
how it applies, or what changes (if any) it would bring.  Pardon my 
saying so but at least in the US, it's the season of politics, and we're 
seeing a lot of this vague "big stroke" pie in the sky painting right 
now.  Unlike most of those, there's a chance with this one to get it 
nailed down to the point it's actually practical.

(Bullet point suggestions for tightening down the spec to something 
"workable" omitted for brevity.  Ciarnm put them well enough.)

> You know... Practical things, rather than things that make you feel
> good but go nowhere.

=8^)

As an alternative or adjunct to Ciaran's suggestions, perhaps this will 
be easier, tho not immediately as complete.  Self-evidently if you are 
making the proposal, you believe there's a need for it and that it would 
change the outcome in one or more events in the recent and possibly less 
recent past.  What about listing them, and how you see your proposal 
changing the outcome thereof.  At least that would give us some concrete 
examples to apply the policy to in our heads as we discuss it.  As I 
said, it's not as complete as the thorough evaluation Ciaranm proposed, 
but one has to start somewhere, and this would be one way to do it.  
OTOH, it's also getting very specific about perhaps sensitive events, 
while Ciaran's proposal would avoid singling out such events and 
therefore people by name, thus having the advantage there as well as in 
ultimate wholeness, once it's done.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list