What we've got here ... is failure to communicate*

Whether they are on scrapes of paper, whiteboards, or formal and elaborate documents, architectures and designs need to be communicated if they are to be of any value. After all, if you fail to explain what you want, how can you expect anyone to approve or follow your directives?

While designs are usually explained verbally, in most cases the verbal explanation is accompanied by some sort of written form. There are many options to document a design:

• UML diagrams. UML offers 13 different diagrams to document both static and dynamic behavior of components. The nice thing about UML is that it is relatively wide-spread and there's a good chance that a technical audience will understand what you want and that UML diagrams also give a professional aura when presented to managers (and they might even make sense to them if they are technical savvy).

• DSDs. Domain specific diagrams. These are diagrams that are specific for a domain few examples include using BPMNor BPEL for busiess process modeling or using DFDs for threat modeling, and so on.

• Code. Probably the best way to explain detailed design, since this is where you are going anyway....
  
  
• ADL. Architecture Description Languages, sort of domain specific languages DSLs) for architecture description. ADLs have some popularity in the academic world,but they are not very popular in "real life". (You can also see an older post I made on ADLs and DSLs).

• "Non-standard" Diagrams. This is probably the most popular way to describe architecture and design since it includes anything not mentioned above. Probably the most common example is using a block diagram for showing layers. The nice feature of non-standard diagrams is that it is easy to match them to the target audieance
  
  

How much documentaiton? That depends on many factors, like the process you are using (agile vs. formal), company standards, customer requirements, how much details are needed to make the point clear etc.

And while you probably like a style or two better than the others, you need to keep in mind that you are not explaining the design to yourself and that you need to match the documentation style to the target audience.

So how do you communincate your designs?

* Cool Hand Luke, 1967

Posted by Arnon Rotem-Gal-Oz at 08:16 AM  Permalink