Re: [AM] ANN: Mashing Deadly Myths

Scott E. Preece wrote:

> 3. We need this documentation. ... Most documentation is written for no
> other purpose than to soothe a bureaucrat.
> ---
> 
> This no doubt explains why the Computer section of your local Borders is
> crammed full of books that try to explain how software works and how to
> use it.

Not all documentation is user manuals. A team with strong internal 
communication can avoid the vast majority of common internal 
documentation (design, functional specifications, and so on).

>The cost of archiving such a document, without worrying about
> maintaining it, may be so small that even a very low probability of
> reuse will still produce a positive expected value to doing so.

But is it worth the risk of becoming out of date, thereby providing 
negative value?

> ---
> | 4. We need a team of specialists. ... What's really necessary is a team
> | of generalizing specialists.
> ---
> 
> I have no problem with this if you describe a "generalizing specialist"
> as "someone who know enough about the roles involved in the project to
> interact effectively with the people in the related roles".  On the
> other hand, if you intend it to mean "every member of the team is
> capable of performing every role", then I disagree vigorously.

I'll venture this: every member of the team is willing to do what it 
takes to make the project a success, including learning to do something 
not in their nominal job descriptions.

The important thing to keep in mind is that no-one will be told "go 
learn X" and sent the corner to learn it. They will have the team's 
support as they go along. Learning in that environment isn't nearly as 
frightening as many people might find it.

> ---
> | 5. The information is lost if it"s only in the code. This statement is
> | clearly false: How can it be lost if you know where it is? The
> | information might be lost to them if the folks in question can't read
> | source code, but isn't the real problem a lack of development skills?
> | Organizations that subscribe to this myth will invest far too much in
> | documentation, increasing their costs, while slowing themselves down.
> ---
> 
> "The code" does not represent all of "the information".  It says nothing
> about what was intended, how it was expected to be used, or why it is the
> way it is (modulo any comments people felt inclined to add).  Stonehenge
> is a nice example - we've got the artifact, but we have only speculation
> about what it's for and how it was used.

We encode what was intended in tests; we encode sample client code in 
tests; if it's necessary to comment and why it is the way it is we add 
comments to the code. If Stonehenge had tests, we could probably figure 
out how to use it.

<snip />
> Inspections, on the other hand, are just one (particularly effective)
> way of finding defects in artifacts. There are other means to the same
> end, and the relative costs and benefits will be specific to your
> organization and project.

Finding defects in artifacts is not enough; being willing to fix defects 
is all that matters. I have rarely been involved in reviews that have 
led to fixes, although I have been involved in many reviews that have 
led to "better luck next time." Fine, but it's too late for this 
project. Pairing would have helped us /now/.
-- 
J. B. Rainsberger,
Diaspar Software Services
http://www.diasparsoftware.com :: +1 416 791-8603
Let's write software that people understand

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: [email protected]

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: [email protected]

TOPICA - Start your own email discussion group. FREE!
http://www.topica.com/partner/tag02/create/index2.html
--^----------------------------------------------------------------