Martin Fowler has a piece on specifying UML diagrams using text. I've never really been that keen on UML diagrams in design documents, mainly for practical reasons:
- Design documents usually have to be written in Word and that means a lot of effort pasting UML Visio diagrams into documents, or trying to get in-place editing to work, which although a great idea has never seemed robust enough to be relied upon. Therefore UML diagrams in a document adds a big overhead, especially when you then have to maintain one or more separate Visio files with the Word document.
- UML diagrams usually appear in A4 or letter size design documents, which means there is simply not enough space to describe a complex design. Imagine trying to cram an architectural or mechanical engineering drawing onto such a small paper size , compared to a typical size of, say, A1.
- I see a lot of design documents which try to buy some legitimacy by including some simple UML class diagrams illustrating class hierachies and not much else. These don't convey much information and waste a significant amount of time in their creation.
Maybe I've used the wrong UML diagramming tools, starting off with Rational Rose which used to be (still is?) an appalling piece of software, but I'd prefer a more textual approach for a lot of design work, something like Eiffel which can be used as a high level design language and which allows you to flesh out the design into an implementation, yet enabling you at any time to view the design without the implementation detail. High-level diagrams can be useful but any more detail and they become counter-productive.