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

Re: [XP] Quality

Expand Messages
  • pschrier@xs4all.nl
    As writing manuals is in this case a prerequisite, I would suggest that in the iteration planning meeting the writing of the documentation a TASK to be done
    Message 1 of 7 , Aug 1, 2001
    • 0 Attachment
      As writing manuals is in this case a prerequisite, I would suggest
      that in the iteration planning meeting the writing of the
      documentation a TASK to be done for each story, just like the writing
      of the code.

      Regards

      Peter

      --- In extremeprogramming@y..., Robert Sartin <sartin@a...> wrote:
      >
      > --- Matthew Davis <azami@s...> wrote:
      > > Yesterday, our customer indicated a strong negative reaction to
      this
      > > situation. He likened it to a service industry situation, where
      you
      > > have to explicitly ask for (and pay for) every little thing. "Oh,
      > > you wanted a bun with your hamburger? That'll be an extra 20
      > > cents."
      >
      > I can't help but challenge the analogy.
      >
      > That analogy applies really well to COTS. I should not buy COTS that
      > claims to solve some problem, only to find that I need to buy more
      COTS
      > or wait for the next version to actually solve my problem. Worse
      still,
      > if I have to spend lots of time giving the vendor feedback and THEN
      pay
      > for the next version to implement what should have been there in the
      > first.
      >
      > Custom software, as developed by XP or any process for developing
      new
      > software, is more akin to paying an architect to design your new
      home.
      > There really shouldn't be features in your new home that you didn't
      ask
      > for. A good architect will remind you to ask for certain features
      > ("Don't you think you need a bathroom on the third floor since there
      > are three bedrooms there?"), but won't randomly insert features that
      > weren't requested ("Oh, I thought you'd like having a trophy room; I
      > didn't realize you don't hunt."). Of course, most new homes don't
      > require documentation much beyond the blueprints (which in this
      analogy
      > are the equivalent of code)....
      >
      > We treated documentation as separate stories for our current
      release.
      > In retrospect, we had a couple of problems with that:
      >
      > 1. The Customer prioritize the documentation below the development,
      > which meant that we had features that were not documented. The
      creation
      > of the document became the critical path to release, much to the
      > distress of our part-time tech writer.
      >
      > 2. Since they were separate stories, the code and the document were
      not
      > always created at the same time. This has made documentation take
      > longer, since the developer had to go back to the implementation to
      > find out what it does. It has also resulted in some documentation
      > errors (because the developer forgot how it really worked and didn't
      > verify with the code).
      >
      > Another way to address the "I shouldn't have to ask for it problem"
      is
      > to treat it as a Motherhood Story
      > (http://c2.com/cgi-bin/wiki?MotherhoodStory). I'm not sure where to
      go
      > on that.
      >
      > I've been considering treating documentation like testing and just
      > requiring that each new story have documentation input deliverd to
      the
      > tech writer. Since we (as in my company, my team) are producing a
      > toolkit to be used by others, the documentation of what we deliver
      is
      > fundamental, so why not create the documentation input for each new
      > feature as it is implemented? I'm not certain this will be an
      > improvement, but it seems to address the two problems we had using
      > separate stories.
      >
      > Regards,
      >
      > Rob
      >
      >
      > __________________________________________________
      > Do You Yahoo!?
      > Make international calls for as low as $.04/minute with Yahoo!
      Messenger
      > http://phonecard.yahoo.com/
    • Ron Jeffries (om)
      ... We can t write documentation without taking time. That will be time taken away from development of the features you want. Would you like to control the
      Message 2 of 7 , Aug 1, 2001
      • 0 Attachment
        Responding to Matthew Davis (01:29 AM 8/1/2001 +0000):
        >As we've proceeded, we've on several occasions (more than I'd have
        >expected for such a small project) had the customer say something
        >along the lines of "has the documentation been written?" We answer,
        >of course, "No, but if you'd like some, you can write a story for
        >that."
        >
        >Yesterday, our customer indicated a strong negative reaction to this
        >situation. He likened it to a service industry situation, where you
        >have to explicitly ask for (and pay for) every little thing. "Oh, you
        >wanted a bun with your hamburger? That'll be an extra 20 cents."

        "We can't write documentation without taking time. That will be time taken
        away from development of the features you want. Would you like to control
        the tradeoff between features and paper, or would you prefer that we just
        use _our_ best judgment about what _you_ need?"



        Ron Jeffries
        www.XProgramming.com
        The practices are not the knowing. They are a path to the knowing.
      • Matthew Davis
        ... In the best possible world, the new team is also XP experienced, and yes, they do read the code to find out what s going on. Hopefully, they also get some
        Message 3 of 7 , Aug 1, 2001
        • 0 Attachment
          --- In extremeprogramming@y..., Paulo Motta <prmottajr@u...> wrote:
          > My point is, if you have a large project and do not have the
          > documentation of the modules, classes and everything else and
          > part of your development team is reallocated to another project
          > because those guys are the only ones who could do the other
          > job. Now you receive a new team that do not know your project
          > because they simply weren't there when the project started.
          > How do you do ? Simply let them read the code and
          > interact with the system to find out what's going on will take
          > too much time !

          In the best possible world, the new team is also XP experienced, and
          yes, they do read the code to find out what's going on. Hopefully,
          they also get some time to pair-program with the old team before the
          transition is completed.

          Reading the code does not take too much time because:
          1 - it is simple and written for legibility
          2 - it has no unnecessary functionality (part of 1)
          3 - coupling is low (part of 1), so you don't need to know the whole
          system in-depth in order to work on one part
          4 - you have a partner, and when one of you misses something important
          the other will catch it
          5 - the code is never out-of-date; even when there is documentation,
          you need to look at the code anyway to find out what's really going on
          6 - the metaphor should help guide you to the right code to do your
          work, and help you understand the overall structure
          7 - the tests explicitly show the expected behavior of the system

          Where this breaks down, of course, is when the hand-off is to a non-XP
          team. Such a team will expect documentation, and will not be used to
          the idea that code can be readable on its own.

          (Many of the XP practices support each other like this. The flip side
          to the above is that if you aren't pair-programming, and don't have
          unit tests, and haven't used test-first design and merciless
          refactoring to keep the code in the best possible shape, then it won't
          work - you'll need supporting documentation.)

          I hope this helps.

          -Matthew
          azami@...
        • Matthew Davis
          Thanks for the advice from experience. ... the ... is ... Now that we ve discovered the need for documentation, I think this is a good way to go. We ll give
          Message 4 of 7 , Aug 1, 2001
          • 0 Attachment
            Thanks for the advice from experience.

            --- In extremeprogramming@y..., Robert Sartin <sartin@a...> wrote:
            > I've been considering treating documentation like testing and just
            > requiring that each new story have documentation input deliverd to
            the
            > tech writer. Since we (as in my company, my team) are producing a
            > toolkit to be used by others, the documentation of what we deliver
            is
            > fundamental, so why not create the documentation input for each new
            > feature as it is implemented? I'm not certain this will be an
            > improvement, but it seems to address the two problems we had using
            > separate stories.

            Now that we've discovered the need for documentation, I think this is
            a good way to go. We'll give it a try next project and see how it
            goes.

            Thanks,
            Matthew
          Your message has been successfully submitted and would be delivered to recipients shortly.