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

[Donnie Berkholz <dberkholz@gentoo.org>]

On 21:33 Wed 28 Nov     , Ciaran McCreesh wrote:
> On Wed, 28 Nov 2007 13:14:05 -0800
> > 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.

I think that in most cases it is self-evident to the developer how much 
documentation is useful, and if the community disagrees with that 
developer, anyone else is welcome to say so. There are always a few 
people out on the edge, but most people realize how much documentation 
should exist. I don't see a benefit to all these precise specifications.

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list