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

Re: Digest Number 1533

Expand Messages
  • woynam
    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
    Message 1 of 33 , Aug 1, 2006
    • 0 Attachment
      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.

      Mark


      --- In scrumdevelopment@yahoogroups.com, "Rohilla, Pryank"
      <pryank.rohilla@...> wrote:
      >
      > Hi,
      >
      > I am a developer doing some support work of an agile project. My
      team mate keep criticising agile methodologies. His points are: Agile
      is not good for Support as it doesn't provide proper documentation of
      developed applications and it's a pain to support projects developed
      using agile.
      >
      > Can some of you agile gurus point out how Agile helps in doing
      support of live applications?
      >
      > Pryank
      >
    • Steven Gordon
      ... Because, keeping information in more than one place is fundamentally flawed. Keeping documentation in synch with something else is a big waste of
      Message 33 of 33 , Aug 4, 2006
      • 0 Attachment
        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
        developers.

        Steve

        >
        >
        > -d
        >
      Your message has been successfully submitted and would be delivered to recipients shortly.