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

RE: XP Documentation (long, but glen asked)

Expand Messages
  • Glen B. Alleman
    Responding to Ron s post... Nice post...but just a few more questions: Documentation in this explanation seems to consist mostly of code in the form of UT s,
    Message 1 of 10 , Sep 1 6:38 AM
    • 0 Attachment
      Responding to Ron's post...

      Nice post...but just a few more questions:

      Documentation in this explanation seems to consist mostly of code in the
      form of UT's, verbal communication among the guys in the same room with
      their customer, some writing on the white board that seems to not leave the
      room or get into electronic form, and programmer's comments in the code.

      The docs that need to go outside the team are as you say "not addressed by
      XP."

      So when time comes to move, and the programmers have to "document" what they
      done for the maintenance folks one question might be - have you seen this
      work? Your C3 example in previous posts didn't keep the docs up to date
      documents and when it was so rudely canceled left you with no maintenance
      docs other than the UTs and code (ST is much more expressive languages than
      Java or C++ it would be very well suited for "self documenting code").

      What "stories" are then needed to "assure" that the hand off is made
      properly. In the past you stated that XP projects are continuous maintenance
      and no hand off docs were needed since the programmers coming on the project
      could learn through PP from the current staff. Would this still be in the
      case in the current description, or would more detailed docs be needed over
      time as the team turns over?

      So in the end from your comprehensive explanation, I read that documentation
      is at a minimum on an XP projects, consisting mostly of verbal
      communication, non-permanent whiteboard UML, code rendered UTs, and code
      hosted narrative. Have I mis-read the post?

      >-----Original Message-----
      >From: Ronald Jeffries [mailto:RonJeffries@...]
      >Sent: Friday, August 31, 2001 7:12 PM
      >To: agilemodeling@...
      >Subject: XP Documentation (long, but glen asked)

      [the big snip]

      >
      >Ron

      Glen Alleman
      Niwot Ridge Consulting

      "Every folly has its reason, which it is never amiss to understand"
      – Jacques Barzun, Science: The Glorious Entertainment
    • Ron Jeffries
      ... Wasn t that actually on agilemodeling, not here? ... Yes. That s where the core of an XP project is, and where the key communications take place. ... Yes.
      Message 2 of 10 , Sep 1 9:12 AM
      • 0 Attachment
        Around Saturday, September 01, 2001, 9:38:49 AM, Glen B. Alleman wrote:

        > Responding to Ron's post...

        Wasn't that actually on agilemodeling, not here?

        > Nice post...but just a few more questions:

        > Documentation in this explanation seems to consist mostly of code in the
        > form of UT's, verbal communication among the guys in the same room with
        > their customer, some writing on the white board that seems to not leave the
        > room or get into electronic form, and programmer's comments in the code.

        Yes. That's where the core of an XP project is, and where the key
        communications take place.

        > The docs that need to go outside the team are as you say "not addressed by
        > XP."

        Yes. We do not specify what to do outside the team, other than the
        reporting notions (Scope Quality Resources Time). Even that is just a
        set of starting ideas.

        > So when time comes to move, and the programmers have to "document" what they
        > done for the maintenance folks one question might be - have you seen this
        > work?

        I am aware of no XP project that has as yet done a handoff.

        > Your C3 example in previous posts didn't keep the docs up to date
        > documents and when it was so rudely canceled left you with no maintenance
        > docs other than the UTs and code (ST is much more expressive languages than
        > Java or C++ it would be very well suited for "self documenting code").

        Yes, C3 was dropped without documents. One could argue, I suppose,
        that we "should" have kept a bunch up to date just in case they shot
        us in the head. I don't think so, as they aren't trying to maintain
        it. In a stupid sort of way, the right thing happened.

        > What "stories" are then needed to "assure" that the hand off is made
        > properly. In the past you stated that XP projects are continuous maintenance
        > and no hand off docs were needed since the programmers coming on the project
        > could learn through PP from the current staff. Would this still be in the
        > case in the current description, or would more detailed docs be needed over
        > time as the team turns over?

        As long as there is no handoff, then the only documentation needed is
        whatever the team needs, which is typically very little. If the
        programmers are transitioning in, pair programming trumps paper docs
        pretty hard, so I'd not expect a lot of documents being needed. I
        would expect a team alert to its own feedback to notice that some
        particular "intro" or whatever would be useful, and do it.

        > So in the end from your comprehensive explanation, I read that documentation
        > is at a minimum on an XP projects, consisting mostly of verbal
        > communication, non-permanent whiteboard UML, code rendered UTs, and code
        > hosted narrative. Have I mis-read the post?

        Inside the project, it turns out that way. Most of the heavier (even
        if not very heavy) docs requirements come about because of outside
        forces. Think about it: if you and I were working in your garage, how
        much paperwork would we need to get our jobs done? I think not much.
        But when we go to ship it, then we'll need something, and because
        we're not dull, we'll do it.

        Does that help? Should it be on the right forum?

        Ronald E Jeffries
        www.XProgramming.com
        The wire is life. The rest is waiting. --Karl Wallenda
      • Ivan Tomek
        Which forum is that? Ivan ... From: Ron Jeffries [mailto:ronjeffries@acm.org] Sent: Saturday, September 01, 2001 1:12 PM To: extremeprogramming@yahoogroups.com
        Message 3 of 10 , Sep 1 9:42 AM
        • 0 Attachment
          Which forum is that?

          Ivan

          -----Original Message-----
          From: Ron Jeffries [mailto:ronjeffries@...]
          Sent: Saturday, September 01, 2001 1:12 PM
          To: extremeprogramming@yahoogroups.com
          Subject: Re: [XP] RE: XP Documentation (long, but glen asked)


          <snip>

          Does that help? Should it be on the right forum?

          Ronald E Jeffries
          www.XProgramming.com


          [Non-text portions of this message have been removed]
        • Ron Jeffries
          ... The agile modeling forum. But the document will be up on my web site shortly. A draft is there now, at ...
          Message 4 of 10 , Sep 1 10:12 AM
          • 0 Attachment
            Around Saturday, September 01, 2001, 12:42:11 PM, Ivan Tomek wrote:

            > Which forum is that?

            The agile modeling forum. But the document will be up on my web site
            shortly. A draft is there now, at ...
            http://www.xprogramming.com/xpmag/Documentation%20in%20XP.htm

            Comments are welcome ...

            Ronald E Jeffries
            www.XProgramming.com
            No one expects the Spanish Inquisition ...
          • Ivan Tomek
            Thanks, I got it now. Still, I am curious, is it possible to join the agile modeling forum? If so, how? Ivan ... From: Ron Jeffries
            Message 5 of 10 , Sep 1 10:34 AM
            • 0 Attachment
              Thanks, I got it now. Still, I am curious, is it possible to join the agile
              modeling forum? If so, how?

              Ivan


              -----Original Message-----
              From: Ron Jeffries [mailto:ronjeffries@...]
              Sent: Saturday, September 01, 2001 2:13 PM
              To: extremeprogramming@yahoogroups.com
              Subject: Re: [XP] RE: XP Documentation (long, but glen asked)


              Around Saturday, September 01, 2001, 12:42:11 PM, Ivan Tomek wrote:

              > Which forum is that?

              The agile modeling forum. But the document will be up on my web site
              shortly. A draft is there now, at ...
              http://www.xprogramming.com/xpmag/Documentation%20in%20XP.htm

              Comments are welcome ...

              Ronald E Jeffries
              www.XProgramming.com
              No one expects the Spanish Inquisition ...


              To Post a message, send it to: extremeprogramming@...

              To Unsubscribe, send a blank message to:
              extremeprogramming-unsubscribe@...

              ad-free courtesy of objectmentor.com

              Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/



              [Non-text portions of this message have been removed]
            • Ron Jeffries
              ... It s on topica.com. Search for agile modeling, two words. It s kind of hard to find ... Ronald E Jeffries www.XProgramming.com You do ill if you praise,
              Message 6 of 10 , Sep 1 10:58 AM
              • 0 Attachment
                Around Saturday, September 01, 2001, 1:34:18 PM, Ivan Tomek wrote:

                > Thanks, I got it now. Still, I am curious, is it possible to join the agile
                > modeling forum? If so, how?

                It's on topica.com. Search for agile modeling, two words. It's kind of
                hard to find ...

                Ronald E Jeffries
                www.XProgramming.com
                You do ill if you praise, but worse if you censure,
                what you do not understand. --Leonardo da Vinci
              • C. Keith Ray
                ... One is describe in a paper somewhere... I can t find it in the book Extreme Programming Examined . Searching the XPUniverse papers... Note that instead of
                Message 7 of 10 , Sep 1 12:09 PM
                • 0 Attachment
                  >> So when time comes to move, and the programmers have to "document" what they
                  >> done for the maintenance folks one question might be - have you seen this
                  >> work?
                  >
                  > I am aware of no XP project that has as yet done a handoff.

                  One is describe in a paper somewhere... I can't find it in the book "Extreme
                  Programming Examined". Searching the XPUniverse papers...

                  Note that instead of doing documentation stories, this contracting company
                  did pair programming to transfer the knowledge of the system under
                  development:

                  http://www.xpuniverse.com/XPU03.pdf

                  Pairing with Client Developers
                  We knew from the start of this project that we
                  would need to hand off our code to the in-house
                  developers in the customers' organization after
                  six or seven weeks. For much of the project, the
                  technical lead from that organization was onsite
                  and working with the development team. There
                  were four other (newly hired) developers that
                  paired with us for differing periods of time
                  during the last three weeks.

                  ----

                  C. Keith Ray
                  <http://homepage.mac.com/keithray/resume.html>
                • Mike Clark
                  ... Pardon my ignorance of C3, but is it in production? I had heard somewhere that it was funded as a research project. Mike
                  Message 8 of 10 , Sep 1 12:59 PM
                  • 0 Attachment
                    Ron Jeffries wrote:

                    >
                    > I am aware of no XP project that has as yet done a handoff.
                    >
                    > > Your C3 example in previous posts didn't keep the docs up to date
                    > > documents and when it was so rudely canceled left you with no maintenance
                    > > docs other than the UTs and code (ST is much more expressive languages than
                    > > Java or C++ it would be very well suited for "self documenting code").
                    >
                    > Yes, C3 was dropped without documents. One could argue, I suppose,
                    > that we "should" have kept a bunch up to date just in case they shot
                    > us in the head. I don't think so, as they aren't trying to maintain
                    > it. In a stupid sort of way, the right thing happened.
                    >

                    Pardon my ignorance of C3, but is it in production? I had heard somewhere that it was
                    funded as a research project.

                    Mike
                  • Ron Jeffries
                    ... C3 started (in XP mode) in 1996, launched in 1997, and was closed down at the beginning of 2001. It may still be paying something like 5 people, but it s
                    Message 9 of 10 , Sep 1 4:12 PM
                    • 0 Attachment
                      Around Saturday, September 01, 2001, 3:59:49 PM, Mike Clark wrote:

                      > Pardon my ignorance of C3, but is it in production? I had heard somewhere that it was
                      > funded as a research project.

                      C3 started (in XP mode) in 1996, launched in 1997, and was closed down
                      at the beginning of 2001. It may still be paying something like 5
                      people, but it's essentially stopped. The project was intended to
                      deliver something useful, but was in fact funded out of IS as a
                      research project, instead of by the customer, which was how Chrysler
                      projects were usually funded.

                      Ronald E Jeffries
                      www.XProgramming.com
                      Fear is the mindkiller. --Bene Gesserit Litany Against Fear
                    • Ilja Preuss
                      ... http://www.topica.com/lists/agilemodeling
                      Message 10 of 10 , Sep 3 1:31 AM
                      • 0 Attachment
                        > > Thanks, I got it now. Still, I am curious, is it possible
                        > to join the agile
                        > > modeling forum? If so, how?
                        >
                        > It's on topica.com. Search for agile modeling, two words. It's kind of
                        > hard to find ...

                        http://www.topica.com/lists/agilemodeling
                      Your message has been successfully submitted and would be delivered to recipients shortly.