Loading ...
Sorry, an error occurred while loading the content.

15205Re: [scrumdevelopment] Re: Agile on documentation & Support (Was: Digest Number 1533

Expand Messages
  • Steven Gordon
    Aug 4, 2006
      On 8/4/06, David H. <dmalloc@...> wrote:
      > 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?

      Because, keeping information in more than one place is fundamentally
      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).

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

      You get what you pay for. I have found passive measures, while
      consumable at any time, are an ineffective way to communicate and
      learn. And it also costs resources to produce and especially maintain
      those documents.

      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


      > -d
    • Show all 33 messages in this topic