Creating Clear Diagrams

We use diagrams to understand, resolve, and communicate on a daily basis.  Given their primary role in most of our techniques, it is critical that we be able to create some clear diagrams.  Here are some tips, if you want to improve your diagramming-fu.

1. Title All Diagrams. Always start by labeling your diagram in the upper left with the UML diagram type, your diagram purpose, and the last modification date.  This:
   1. Is a constant reminder of the scope (for you!)
   2. Sets the topic for your audience
2. Fit your diagram on on standard letter size paper. Clearly, there are situations where it makes sense to break this rule, but this is a good rule of thumb that:
   1. Helps keep your diagrams with the right amount of information to be easily understood by your stakeholders.
   2. Makes it easier to print and embed the diagram in documents.
3. Diagram with a goal. Only include “fit to purpose” items on a diagram. One of the keys to “right-sized” diagrams is to only diagram what you need to be successful. e.g. If you are designing a solution in an Enterprise where every desktop contains Microsoft Word, you don’t need to include a component for Microsoft Word on the diagram unless the solution has some dependency or impact on it.
4. Separate “concerns” onto separate diagrams. Is the diagram for the hardware team? What is important to them? Probably not the same things that are important to the code deployment team. This is a balancing act. You don’t want to have to maintain multiple similar diagrams, but, conversely, it is easy to over-populate a diagram with information and reduce its effectiveness. Any information that is not of use to your diagram audience is nothing more than noise and distraction to them.

Dan Hughes  is a principal consultant and partner at Systems Flow, Inc., where he leads the technology services practice. He has 20 years of software engineering experience spanning a broad range of technologies and techniques. Startup to enterprise, he has launched, managed, and executed all aspects of both product and enterprise life cycle, delivering complex, enterprise-scale architectures for clients in the public and private sector, in industries ranging from banking and insurance to international development. Dan holds a Bachelor of Science in Computer and Systems Engineering from Rensselaer Polytechnic Institute. For more details, please visit Dan's LinkedIn profile Read more blogs by Dan Hughes

Comments