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

[Ciaran McCreesh]

On Wed, 28 Nov 2007 13:14:05 -0800
Donnie Berkholz <dberkholz@g.o> 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.

Which still doesn't bring anything discussable or implementable. 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.

> What remains unclear about this principle?

It's entirely nebulous and has nothing that can be discussed or agreed
upon, beyond giving people a feel good "ooh, yes, we should do this"
with no practical purpose. 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.

So, if you want to take this somewhere useful:

* Decide what the scope of a change is. Are we talking anything
user-visible? Anything substantially user-visible? Anything requiring
user action? Anything developer-visible? Anything requiring developer
action? Anything visible to small numbers of developers working in a
specific area?

* Decide what the appropriate level of documentation is.

* Discuss how you're going to get documentation of a sufficiently high
quality. Most developers aren't going to go out and spend several months
studying technical writing...

* Decide whether it's worth putting the limited available writing
resources into developer documentation that will only be read by a few
hundred people, rather than putting more focus into user documentation
that will be read by pretty much everyone.

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

-- 
Ciaran McCreesh