Re: Digest Number 1533
- Ask your team mate if he'd like some comprehensive documentation that
was consistently wrong.
In my experience, and that of many others, documentation never keeps
up to date with the application. If it does, then the chances of the
application meeting the real needs of the business are low, as more
time is spent working on the documentation than the actual app.
Lastly, please keep in mind that agile methodologies do not say that
there should be *no* documentation, just the right amount of
documentation. If the product owner feels that a support guide
provides value, then a support guide should be produced.
--- In email@example.com, "Rohilla, Pryank"
>team mate keep criticising agile methodologies. His points are: Agile
> I am a developer doing some support work of an agile project. My
is not good for Support as it doesn't provide proper documentation of
developed applications and it's a pain to support projects developed
>support of live applications?
> Can some of you agile gurus point out how Agile helps in doing
- On 8/4/06, David H. <dmalloc@...> wrote:
>Because, keeping information in more than one place is fundamentally
> On 04/08/06, Steven Gordon <sgordonphd@...> wrote:
> > On 8/3/06, David H. <dmalloc@...> wrote:
> > >
> > > And as mentioned here before, in such situations go revisit DITA
> > DITA? Would that be "Darwin Information Typing Architecture"?
> > If so, I do not believe any single predefined information meta-model
> > can be appropriate for all projects (unless you melt down to trivially
> > atomic knowledge representations like ER). Even if it was, I do not
> > see how it would solve the problem of static information inevitably
> > getting stale and being a poor substitute for timely communication and
> > collaborative feedback.
> What is "static information" ?
> Every piece of documentation is as alive as you keep it.
> Now if every story develops a task that reads "keep documentation in
> sync" or whatever you call it, PLUS the fact that you can
> auto-generate a hell of a lot of documentation, I do not quite see why
> this picture of big monolithinc, static documents is dso prevelant?
flawed. Keeping documentation in synch with something else is a big
waste of resources. In practice, you get:
1. Resistance to change because the cost of change is at least double, or
2. Documentation not kept up to date when the going gets tough, or
3. Both (the usual case).
Of course, autogeneration is a fine option (although I do not
understand why DITA would be a more useful format than UML). Better
yet is expressive, readable test code that specifies what each
component/class of the system does in a verifiable manner (so that you
know when either the spec or the system is wrong).
>You get what you pay for. I have found passive measures, while
> > Yes, it is important that the domain model in the head of every
> > project member is compatible, but codifying it formally does not
> > guarantee that mental models agree nor does it solve the major issues
> > involved with communication, mutual understanding, and ramping up new
> > people.
> Ramping up people costs money. I appreciate that this is a necessity
> in any project under any methodology, but written documentation is
> passive and can be cosumed any time, any where. Ramping someone up
> through communication and interaction will most likely produce better
> results because there is an immideate feedback loop, but it costs a
> lot more money.
> If you can combine both approaches I would argue that you get
> excellent results, no?
consumable at any time, are an ineffective way to communicate and
learn. And it also costs resources to produce and especially maintain
I know personally, that if you pair me with the individuals on any
team in any technology in any domain while they are doing the work
they would normally be doing, I will learn much more effectively than
by sitting in a cube by myself reading. Furthermore, I would be
contributing value to the team from day, if only by questioning code
and practices that the team has gotten into the habit of doing without
thinking about why.
At least in my case, it costs more for an organization to pay me to
read documents because pairing returns immediate value and trains me
up faster. I do not think I am unusual among professional software