Is UML still seen as a viable way of documenting a

Question

Is UML still seen as a viable way of a documenting a software design?

Extra points for references that back up any claims :)

Answer 1

UML should be used as a communication tool. It is definitely a valid means to communicate designs and gives developers a common language to discuss those designs before implementation.

The best way to document your design is by writing clean code. UML, like all other documentation, tends towards entropy.

Here's the best reference I could find

Answer 2

UML is only a method for visualising some aspects of a software design. It cannot be used alone to document a design.

Answer 3

I prefer using autogenerated UML (source code -> UML) to visualize the implementation of a system. I find that static documentation is often useless and sometimes misleading.

Answer 4

The UML is just a standard notation for representing a design, it's not a process or an approach.

Answer 5

The talk How to Represent the Architecture of Your Enterprise Application Using UML 2.0 and More held by Paulo Merson at JavaOne 2006 describes various approaches for documenting an architecture, both with and without UML. There's more info at Architecture Documentation, Views and Beyond (V&B) Approach, describing an approach advocated by the Software Engineering Institute (SEI).

Answer 6

I am responding to the new version of the question which speaks to UML as a documentation tool. I will try and role in UML as a communication tool as well, because they are one in the same.

Context: This perspective is driven of my daily job as an Architect having to design across hundreds of systems/software, 10,000 hour+ efforts, and maintaining consistent documentation and practices for a portfolio of systems. This means that I have had to grapple with documentation quality, consistency, and definition many times.

Summary: What else is there? Sure you can discuss levels of documentation, is UML really better than reading code for conditional logic? Likely not, but on a whole there is no real alternative if the problem space is large enough.

If UML is nothing else it is for documentation and communication. "UML Distilled" written by Martin Fowler, which is nearly the defacto standard for UML books, carries this opinion. Fowler, if I read correctly, believes UMLs primary use is for communication, which documentation is, just the static kind. Not so much low level specs and code generation.

IBM, Borland, Microsoft, and Eclipse support UML with large complex tools. Many other smaller or targeted vendors also provide UML tools. I am not aware of a more accepted/implemented diagram/modeling standard out there.

Additionally consider the alternatives, what diagram notation is more common? Why not use what most people know. Most colleges/university if they teach any diagramming or modelling use UML. Other than some flow or conditional logic diagram styles there is not much else out there, well documented and standardized.

Standard notation is even more critical that what most people know. In large projects you can't always read the code, talk to the person that wrote it, or ask the business partner what they wanted again. This is where standards are key. Inconsistent usage will cause confusion, and it really will if people are allowed to invent or add to the symbols in an informal way. Additionally, you don't want to create a document and always have to explain what you meant.

Never invent unless you have too, which is the most likely alternative to UML. Think about every time a new person joins the team or company. What does a box mean, arrow? Can this arrow connect to this triangle in this direction, and what does it mean? You basically have to invent a domain specific language/model. So you need a training presentation, tutorials, examples, review work, schedule training sessions, maintain the invented documentation method etc. Then of course you switch out-task partners, or hire a new person and you have to do it all over again. Let people focus on learning the systems not your documentation method, or if the have to make it transferable knowledge or skill like UML. Let the experts focus on coding and designing, not inventing a documentation/diagram standard.

To all the UML critics I do not live in a ivory tower or glass bubble, I have to live with hundreds of different documentation methods everyday as people invent them or I am looking at the next vendor technology. UML is not perfect, but it is the most common, is good enough, and not trivially replaceable.

Valid additional questions:

• What should I document visually with UML, where can code comments take over?
• What span or aspects are more important?
• What might be a consistent set of artifacts that work for my kind of systems or applications? (This is a critical question if you work in an enterprise with hundreds of applications/systems)
• Where do we store the documentation and make it searchable and discoverable.