Positive experiences with software development
Vitaliy email (remove spam text)
"Alan B. Pearce" wrote:
> >OK, as long as the assumption is not that someone totally
>>unfamiliar with the project would be able to use the
>>documentation to learn everything they need to know about
> I guess the thing here is to limit the capabilities of the person who is
> unfamiliar with the project - to someone who would have the necessary
> knowledge and experience to have been involved in the project previously.
> I.e. you are not documenting the project so that a fresh apprentice can
> understand it - which is what it sounds like was happening on the one
> you got overwhelmed by paper.
While your guess is true in part, I think there is a more fundamental
problem. The guy we contracted was an expert in the field, completed a
similar project previously, and even published the results. I'm sure he was
more than capable of successfully completing the project, and that our
methodology was what killed it.
There are several problems with software documentation:
1. It's not interactive. You can't predict which parts will not be clear to
the person reading the docs, and it's likely that different people would be
confused by different things.
2. The natural response to try to alleviate #1 is to produce increasignly
detailed, comprehensive specifications. Lots of extra work, most of it
unnecessary, and counter-productive in terms of its usefulness to the person
it's intended for (imagine trying to find something in a 40,000 page spec).
3. It can quickly get out of sync with the code (and often does).
Possible ways to keep the spec from reaching unmanageable size:
- Try to keep programmer turnover to a minimum, and ensure a smooth
transition (let new programmers assimilate before the old ones leave).
- Write self-documenting code
See also: www.piclist.com/techref/index.htm?key=positive+experiences
You must be a member of the
piclist mailing list
(not only a www.piclist.com member) to post to the