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

documentation

Expand Messages
  • wbarr@cips.com
    If you are down on Framemaker, try LyX. http://www.lyx.org/ I m not familiar enough with it, yet, to give any comprehensive review, but it seems to be working
    Message 1 of 2 , May 22, 2000
    • 0 Attachment
      If you are down on Framemaker, try LyX. http://www.lyx.org/

      I'm not familiar enough with it, yet, to give any comprehensive review, but it
      seems to be working nicely for my requirements at the moment.
    • 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 2 of 2 , Sep 1, 2000
      • 0 Attachment
        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.