Re: [AM] ANN: Mashing Deadly Myths

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.

You are absolutely right in saying that the cost and benefit of each
documentation item should be considered as any other project
deliverable.  You need to consider the expected benefit of writing the
document, which includes the cost of writing it when the information is
already gathered, the cost of rediscovering that information later, the
probability of needing to rediscover it, and the value of the
information to the downstream user.

You shouldn't be creating documentation that won't be used. Note,
however, that many documents are simply the by product of making a
decision or doing a design and the document IS used during the process
of making the decision or doing the design, whether it is used downstream
or not.  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.

---
| 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.

Just as you wouldn't expect the person who designed the battery on a
cell phone to be qualified to also design the antenna, you shouldn't
expect that the person who designs the user interface is capable of
designing the code that implements the it, let alone of designing
Level 1 of the air interface stack or speech coding algorithms that will
run in the DSP.  They just need to know each others' domains well enough
to communicate about needs and interactions at the interfaces between
domains.

---
| 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.

---
| 
| Myth-Masher: Again, this solution calls for building teams of
| generalizing specialists, people with the confidence and ability to work
| with the wide range of artifacts created during development. If you
| focus on writing high-quality code and putting documentation in the
| single most appropriate place (which is often the code), people will
| start to see this as an incredibly effective way to work. All I?m
| suggesting is that you apply the fundamentals of data normalization, the
| desire to store information in one place only, to documentation.
---

I have no complaint with this suggestion, just with the original
assertion that "the code is enough".

---
| 6. We need a detailed process definition. Just as bureaucrats think that
| you?ll read documentation, they also assume that you?ll read and then
| follow defined software processes. The only time that I?ve ever seen
| anyone read a process definition is when they?ve never done the job
| before....
| 
| Myth-Masher: In reality, your process definition efforts are usually for
| naught. You?re better off developing a high-level overview of how things
| should work, producing templates and examples of key artifacts, and then
| ensuring that everyone is given the training and mentoring they need to
| gain the skills they require.
---

My experience is that you can't build the training, templates, examples,
and overview, without doing all the work that would produce the detailed
description.  That is, the writing of the detailed description is a wart
on the side of the effort of developing the information it represents,
which you DO need.

| 7. We need to review this artifact. Too much faith is put in reviews and
| inspections, and when they?re done well in the right situations, they do
| produce results. However, reviews are compensatory practices?they
| compensate for communication barriers such as disparate locations, which
| result in inconsistencies between artifacts; little or no artifact
| sharing, which allows people to get on the wrong track without being
| caught for awhile (if ever); and overspecialization of skills, which
| results in narrowly focused decisions that ignore the bigger picture.
---

Reviews and inspections are different animals. Reviews are intended to
align thinking, inspections are intended to identify defects.

In organizations where colocation, simultaneity, and continuous
involvement are not practical, reviews are critical. If you want to
develop rules that apply only to projects small enough to get every
stakeholder involved in every decision, your audience is a very small
subset of the software development world.

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.

scott
-- 
scott preece
motorola urbana design center (il67), 1800 s. oak st., champaign, il  61820  
e-mail:	[email protected]	fax:	217-384-8550
phone:	217-384-8589	cell: 217-433-6114	pager: [email protected]

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
--^----------------------------------------------------------------