How to use UML and DDD in technical writing like user manual, or requirements, specifications, design document, or test plan

How to use UML and DDD in technical writing like user manual, or requirements, specifications, design document, or test plan

You may say: the title is biased: it means that UML is just a tool for drawing pictures. My answer: correct, if only you remove “just”: it is not easy to draw intuitive pictures for all audiences across board: end users, stakeholders, managers, architects, programmers, testers, and supports. UML can do that – if you use it carefully.

The operative phrase is, “if you use it carefully”, hence the title: how to …

However, before getting into the details, I want to emphasize that except for very large projects and you have all the time, money, and people to make sure everything is synchronized, you must always insist on using one and only one core document across all phases of the life cycle of the software. It is a crucial technique. I have seen too many projects getting into deep troubles, simply because of using too many half-cooked documents and finally giving up effective and necessary documentation, and getting into a big mess.

Doing this requires developers learn to use domain concepts even in “technical” discussions, otherwise, the “design” will not be readable by “end users”, and that will break the “one core document” rule.

This was always a “theoretical headache” for me, because I used this technique for a very long time, and there was no problem in practice once you “get it”. However, to “get it”, the only way is for me to show people how to do it. It was really a pain, because I always felt that this was just a hack for “really small projects” (when in reality it can be used for large projects).

DDD (Domain Driven Design) cures my headache: if you use the ubiquitous domain language, then, (power) end users can understand most of your “technical” discussions; for the parts that they cannot understand, then, do not put it in the core document, because they are not that important after all!

The number one rule of the how-to is that do not try to use UML to replace plain English (or any natural language you prefer). The main body of the document is plain technical writing.

The reason for that is that both sides of the extremes prefer plain English than diagrams: end users and programmers. End users like diagrams only when those diagrams have sufficient text explaining them. Also, you may be surprised that programmers prefer plain English also. It is true, because higher-level language is modeled after plain English! You may say, then, who likes diagrams? Methodologists, of course! Seriously, too much diagrams is a sure sign of the immaturity of the analyst.

The core document should always split into two parts, one starts from a glossary; one starts from a list of existing applications, ordered by a typical top level work flow (note: if there are many “typical” ones, just pick one that is most “typical” and most complete). Note that if some workflows, or, some parts of some workflows, are not covered by existing (i.e. “legacy”) “applications”, then, simply assume it is a “brain-and-paper application”, and group and list those major data sheets.

Those two parts will co-evolve. We should split them apart, because they tend to evolve in different rhythms and granularity. However, it is extremely important that conceptually, those two parts belong to one document.

The glossary can be enhanced by ER diagrams. A lot of times, that is sufficient. However, we can use class diagrams instead, or, use both ER diagrams and class diagrams.

For all business applications, when you use class diagrams, just treat them as ER diagrams. DO NOT pay attention to behaviors. I know, a lot of “classic” OOAD teach you the opposite. Ignore those pedantic stuff; they have no idea about distributed computing and Service Oriented Architecture. Also, note that do not use “aggregate” (the empty arrow) in class diagram. If necessary, you can use composite (the solid arrow).

Then, what is the difference between class diagrams and ER diagrams. Not that much. In class diagram, you are closer to coding, and therefore, perhaps you can generate some code, or, more practically, you can get reverse engineering diagrams from code (but you can get ER diagrams from database also).

If it is a large project, you can use package diagrams and deployment diagrams. However, a lot of times, a simply paragraph is enough. Then, again, pictures are good for presentations, and help discussions.

Class diagrams are always necessary for the “glossary” part (that is, if you count ER diagrams as a variation of class diagrams). As a result, it is the (only) necessary UML in those technical writings. In addition, state diagram can be very helpful for some non-trivial state-oriented classes.

For the “application list” part, we do not “need” any UML diagrams. However, sequence diagrams and activity diagrams can be helpful for presentation and therefore for group discussions.

The majority of the content of the “application list” part are screen shots (or data sheets for brain-and-paper computer), using the typical flows. We need plain English to describe the screen flows, and, more importantly, the behaviors of those buttons in those screens.

Those descriptions are scenarios of “use cases”. Note that the “pure” use cases do not go with screen shots. However, without mockups, users will get confused and we will get the wrong information until too late. I have seen too many failures because of this. I am convinced that it is not whether, but when, for users to get confused and the team makes fatal mistakes. Note that “confused” also means that users are simply not interested, because: “there are no screens, they must not real, so, why bother”.

Both activity diagrams and sequence diagrams are helpful for complicated use cases. Sequence diagrams are less useful, because they tend to be too low level for users. Activity diagrams are useful for workflows. However, do not try to draw activity diagrams for every use cases, only the “interesting” ones that need discussions and attentions. In Activity diagrams, pay special attention to fork and join, and decision and merge. Always use merge explicitly. When you use sequence diagrams, you need to pay attention to the “activation bar” (or, whatever you call it) and frames (added in UML 2), for non-trivial flows – again, perhaps it is NOT a good idea to use sequence diagrams: you will find that either the workflow is too simple to use a diagram, or, the sequence diagram is too awkward for complex workflows!

Activity diagrams will be more and more popular, because more and more platforms are supporting workflows directly.

Use case diagrams are not that useful, it is simply a table of contents, with links (“includes” and “extends” etc.).

Summary: one core document for all life-cycle phases using ubiquitous domain language, split the core document into “application list/flow” and “glossary (for the ubiquitous domain language)”, use plain English; class diagram, state diagram, package diagram, deployment diagram; use case with mockups, activity diagram, sequence diagram.