On Wed, 28 Nov 2007 13:14:05 -0800 Donnie Berkholz <[EMAIL PROTECTED]> 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
signature.asc
Description: PGP signature
