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

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

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

Answer 2

Thinking is the only viable way of designing software.
UML is sometimes seen as a viable way to partially describe the design you came up with.

Answer 3

UML is a way of visually presenting a design, not the actual design method itself. It's just a tool that you use along your travels. As far as I know it is still pretty prevalent in the software engineering world because it is a standard and can be used to convey ideas between two people effectively (which is why it is referred to as a language).

Answer 4

UML, as @John Topley pointed out, is just a standard notation for describing aspects of an object-oriented design, so your question doesn't quite make sense.

Personally, I find class diagrams to be the most useful aspect of UML; I seldom bother with most of the other stuff, as I find it easier to write short, descriptive documentation explaining interactions and behaviours. Class diagrams, however, provide a reasonable overview of the architecture.

One thing to keep in mind is that you shouldn't necessarily worry too much about writing "perfect" (i.e. normative) UML; the most important thing is to make sure people understand your design. That said, be careful about accidentally abusing notation, because that may well confuse people who are expecting things to have a specific meaning. If in doubt, annotate with text to be clear about what's going on.

Answer 5

UML is more of a way to visualize the design of a system, not really a process to do that design. Although being able to visualize does help the design process.

That being said I do like and use UML when designing more than a basic architecture.

It is very helpful when designing to be able to see how all the parts fit together. Many times a design will show architecture shortcomings when doing the UML, before any coding has started.

It serves as a good reference for getting people up to speed on how a system works, and it is useful when you come back to that code later and say, "How did I design that again?"

Basically to answer you edited question, yes, it is useful to document a system design because many people already know it, and, as already pointed out, there are many tools that support it.

Answer 6

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: http://tinyurl.com/nux8ov

Answer 7

The question sounds slightly back-to-front to me... I don't think UML is intended as a tool to design software, so much as a tool to document a design (in progress).

In my opinion, UML can be a valuable tool for such documentation since it standardises a number of views on a design... but by no means the only valid one. Any design document that is sufficiently clear and well written will do the job, even if it has no UML in it.

Answer 8

IMO, UML lost much of its image as the only-and-always-best solution for software development. While enthusiasts in the beginning (ans some still) are in the opinion that UML will solve design problems and everything should ideally be drawn with UML. Reality proved that it is not much better then any other kind of diagram.

IMO, UML is now widely seen as it actually is: a standard for many diagrams needed in oo analysis and design. It is the indeed the most popular diagram standard in use. There are many more tools around and many more people know UML then any other diagram style.

Answer 9

UML can become part of the process of design and implementation. Enterprise Architect has some great tools for initial design. UML falls flat when this isn't backed up by their additional tools of re-importing after customization to update the design. It really does a good job of displaying your current structure, and allowing you to add detail in terms of other UML diagrams (Use Cases, State Diagrams, User Interface mockups and more).

Sadly though, UML really isn't used to it's full potential in practice.

Answer 10

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 11

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 12

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

Answer 13

In my opinion well written and well commented code speaks for itself and having UML diagrams would just be repetitive and useless.

Answer 14

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.