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

[extremeprogramming] Re: I got the books this weekend! Hooray!and questions...!

Expand Messages
  • Brougham
    Phil... ... isn t ... No comments are better than inaccurate comments. Documentation that is not kept current may or may not be a reflection of reality.
    Message 1 of 2 , Feb 1, 2000
    • 0 Attachment
      Phil...

      > Ron Jeffries wrote:
      > > The trick is to do only documentation that is actually used. If it
      isn't
      > > used, destroy it, don't update it.
      >
      > I don't get how you add value by throwing it away. Not updating it I
      > get, but why throw it away?

      No comments are better than inaccurate comments.

      Documentation that is not kept current may or may not be a reflection
      of reality. Later, somebody may read the documentation and assume
      that it is accurate. After all, why would anybody keep inaccurate
      information about their project?

      __________________________________________________
      Do You Yahoo!?
      Talk to your friends online with Yahoo! Messenger.
      http://im.yahoo.com
    • Phil Goodwin
      ... Maybe I m just a hopeless cynic, but I never believe the documentation I read about a project. All I hope for is that it s enough to give me the background
      Message 2 of 2 , Feb 1, 2000
      • 0 Attachment
        At 04:32 AM 2/1/00 -0800, you wrote:
        >Phil...
        >
        > > Ron Jeffries wrote:
        > > > The trick is to do only documentation that is actually used. If it
        >isn't
        > > > used, destroy it, don't update it.
        > >
        > > I don't get how you add value by throwing it away. Not updating it I
        > > get, but why throw it away?
        >
        >No comments are better than inaccurate comments.
        >
        >Documentation that is not kept current may or may not be a reflection
        >of reality. Later, somebody may read the documentation and assume
        >that it is accurate. After all, why would anybody keep inaccurate
        >information about their project?

        Maybe I'm just a hopeless cynic, but I never believe the documentation I
        read about a project. All I hope for is that it's enough to give me the
        background I need to understand the code.

        Maybe that's why I value all of that old stuff: because the way I use it
        means that it doesn't have to be accurate, just representative. If I have
        two different design documents and code for the same part of the system I
        don't see a bunch of useless documentation for code that I still don't
        understand, I see a trajectory. Maybe it shows me the next likely step in
        the codes evolution, maybe it shows me an underlying problem that hasn't
        been worked out, maybe it just shows me how my new teammates think. As long
        as there isn't an ocean of it to wade through it's almost always enlightening.

        Phil
      Your message has been successfully submitted and would be delivered to recipients shortly.