

Ask HN: Is UML the best option design documentation? - jasongullickson

For design documentation, is there something better than UML?
======
hga
I would worry a lot more about a process that keeps the design documentation
in sync with the code and systems than the form it takes.

Design documentation violates the Don't Repeat Yourself (DRY) rule and how
often have you seen it, especially at the fine grained level of UML, keep up
with the code instead of being abandoned early in the process?

So maybe you should look at round-trip tools, or methods to automatically
generate documentation from easy (enough) to maintain in your code stuff
(Javadoc is one well known low level example of this).

Or keep it so simple it won't be a burden to keep up to date, but then you're
probably not talking an all-in UML approach.

~~~
jasongullickson
Good point, and I've definitely been there before (sort of the problem I'm
trying to solve at the moment, actually).

...that said I fear that most code-sync'd documentation is too low-level to
use for communication between programmers and non-programmers so the
documentation I'm creating may be necessarily decoupled; unless you've seen
something I've overlooked (please? :).

~~~
hga
No, sorry, if I knew of such I most certainly would have told you! ADDED:
Rational was trying this, don't know how far they got ($$$, note they're now
part of IBM).

Aside from Literate Programming, which is just another form of (verbose)
commenting and even further violates DRY.

