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

Re: documentation

Expand Messages
  • Dave Thomas
    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
    Message 1 of 2 , Sep 1, 2000
      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
    Your message has been successfully submitted and would be delivered to recipients shortly.