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

Re: [XP] Re: documentation

Expand Messages
  • Tom Clarke
    And these could be stories: - System administrator needs to know how to restart server -Tom ... From: Dave Thomas To:
    Message 1 of 1 , Sep 1, 2000
      And these could be stories:
      - System administrator needs to know how to restart server


      ----- Original Message -----
      From: Dave Thomas <Dave@...>
      To: <extremeprogramming@egroups.com>
      Cc: <kentbeck@...>
      Sent: Friday, September 01, 2000 10:19 AM
      Subject: [XP] Re: documentation

      > My take on this documentation issue is that it is a non-issue.
      > When you write a system, you are continuously communicating your ideas
      > and intentions. You are communicating them to computer, so it can run
      > the application that you're envisaging, and you're communicating them
      > to the future--to those folks who have to pick up your legacy and work
      > with it. Because you yourself may well be one of those people,
      > self-interest dictates that you communicate well.
      > So the issue isn't one of "document or not." Instead it's "how do I
      > maximize the information that can be extracted from what I'm doing?"
      > Many of XPs practices help here: unit tests document functionality,
      > consistent coding style aids readability, and an absence of make-work
      > documentation means that what's left is essential reading.
      > So, when you're faced with a decision on whether to document, ask
      > yourself the question: will writing this communicate something
      > significant? If the answer is yes, then ask yourself a second
      > question: if this is so important, can I make this document the
      > definitive source of the information--can I derive artifacts such as
      > code or database schemas from it? Use the DRY principle: each piece of
      > knowledge should be represented just once.
      > Do it this way, and the distinction between documentation and code
      > blurs, and the question becomes moot.
      > Regards
      > Dave
      > To Post a message, send it to: extremeprogramming@...
      > To Unsubscribe, send a blank message to:
      > Ad-free courtesy of objectmentor.com
    Your message has been successfully submitted and would be delivered to recipients shortly.