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

Re: Documentation

Expand Messages
  • acockburn@aol.com
    ... The converse situation is also interesting (two recent times someone came to our meetings and said): Our system is in terrible shape... no one on the
    Message 1 of 105 , Sep 1, 2000
    • 0 Attachment
      --- In extremeprogramming@egroups.com, Russel Hill <russh@s...> wrote:
      > As I mentioned in a previous post... I've been on the other end of
      > this one. Taking over a project after the original development
      > team left..
      > While the docs may be REQUIRED, they may or may not actually help
      > the new team. In our case, ... they did not.

      The converse situation is also interesting (two recent times someone
      came to our meetings and said): "Our system is in terrible shape...
      no one on the original team is left and we can't figure out how the
      system work... We can't maintain the thing into the future any more,
      we're faced with throwing it away and writing a new one."

      Kent poses the thought: "IF you had really clear code and functional
      tests and unit tests and a significant group of the developers, THEN
      you wouldn't need written documentation."

      I find that to be a vacuuous IF statement in most cases.

      Replace with the thought: "IF you have the normally messy code and
      maybe some functional and unit tests, and nobody is left over from
      the original team, THEN what would you want/need in the form of
      (possibly not written) documentation?"

      OK, that is already too far to the other side. Let's find a thought
      in between: "We're going to do a PAP project (Pretty Adventuresome
      Programming). What are the odds that we'll end up with really clear
      code and functional tests and unit tests and remaining with a
      significant group of the developers?"

      (I'll bet you the odds are very close to zero.)

      "And so, what should our strategy be for laying down tracks of where
      the team has been during the design of the system?"

      What I get is that a true XP project that really generated clear code
      and is lucky enough to keep at least 2 of its developers around
      forever does not need documentation, but that PAP projects do need
      documentation of some sort. "sort" to be determined.


      Alistair
    • David H
      ... There is none. Both do completely different things. Have a look at: http://www-306.ibm.com/software/globalization/topics/dita/index.jsp or
      Message 105 of 105 , Sep 7, 2006
      • 0 Attachment
        Paul wrote:

        >
        >
        > so what's the benefit of DITA versus NDoc?
        >

        There is none. Both do completely different things.
        Have a look at:

        http://www-306.ibm.com/software/globalization/topics/dita/index.jsp

        or

        http://www-128.ibm.com/developerworks/xml/library/x-dita1/

        To better understand what the intent behind DITA is.
        Basically you are trying to single source _all_ documentation based on a
        topic structure. Thus being able to generate End user documentation and
        Technical documentation, developer documentation and so on, from the
        same source.

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