Yes. - But is "out-of-date" the problem? "round-trip" UML tools, auto-generating UML from code, seemed like a great idea once (e.g. Rational, Together), auto-

Yes. - But is "out-of-date" the problem? "round-trip" UML tools, auto-generating UML from code, seemed like a great idea once (e.g. Rational, Together), auto-keeping UML up-to-date. They don't seem popular now. - Is UML the problem? (IMHO: no. It's good enough to be useful; like, no matter how bad XML is, it does work). - Or is it that the devil is in the details, and you just can't summarize code? IMHO, docs of architecture would be the most useful of all docs. Design patterns, javadoc-like tools, type-systems and UML all try it. In the end, understanding the domain problem is the key to understanding the solution approach, which is key to understanding its architecture. That's a lotta understanding. In practice, I inspect source, stepping through manually - your way's better.