Someone really smart has once said “a picture is worth a thousand words”. Isn’t it why we use flipcharts and whiteboards all the time? It’s so easy to make your point and focus your group’s attention if you have a graphic representation of what you’re speaking about. Why don’t we do it in our specifications then? Why don’t large enterprises have any formal diagramming standards (trust me, they don’t)? I’ve been in the company like that for 8.5 years, but during that period I haven’t met anyone else who uses UML or BPMN in project documents. Why?

  1. Because you have no guarantee that client people will understand your drawings
  2. Because there’s much higher chance of misinterpretation in case of drawings
  3. Because it’s hard to express low-level details in drawings
  4. Because sometimes tiny change in subject requires total overhaul of drawings (because of notations being formal)
  5. Because Visio is terrible…
  6. Because if you put too much info, picture gets unreadable and you can’t limit detail level in picture
Anything else?

Some of these points are truly valid. Visio is truly a pile of stinking… errmm, sorry. Where was I? Ahh, ok.
 
Points 1, 2 & 3:

Yes, you can’t rely on your pictures when you need to have client’s signoff. But the key is to use drawings as a protocol of communication between educated people. Drawings are like design patterns in software engineering - sometimes it’s enough to have a one single look and things  are becoming more than obvious to you. It doesn’t mean that all what you have to do is to prepare 100 drawings and text description is obsolete. Pictures should be meant to be an additional clarifications - they may lack some details, but they are perfect to refer to, when someone reads a complex and long description of something.
 
Points 4, 5 & 6:
 
Use your tools wisely. Visio is a little bit like Paint. It allows you to draw some stuff, but it doesn’t care what all those symbols really should represent. It means that if you’re going to prepare a 2nd diagram and you’d like to use some entities you’ve used on the 1st one, you can either draw them once again or try to copy and paste them. If you want to prepare another diagram with an overview (on higher level than previous ones), you have to draw some shapes that represent the same entities, but in a different way (less detail, smaller graphic symbols, some generalization  etc.) - but if you change the name of component on one of diagrams, it won’t be automatically changed for others representations of this component in other diagrams - you need to do it manually.
 
That’s why Visio is no-go. Absolutely no-go. What you really need is a tool, that lets you draw some formal, standard diagrams and puts all logical elements you use in some kind of repository. This repository has to deduce relationships between those elements due to what you’ve drawn. This way, if you want to re-use a component on a new diagram, you just re-use the component without any need to input the data once again. If you change element’s name - this change will be immediately reflected in repository and (automatically) in other diagrams. This way:
  • it’s very easy to prepare different-level perspectives of model
  • one simple change in described reality won’t force you to (most likely) manually change tons of diagrams
  • if you’re trying to do something illegal in particular notation, tool should be able to at least generate a warning (as your input won’t fit in repository)
Many tools that work that way, may give you even more:
  • ability to re-create diagrams from actual code / database structure, etc.
  • the other way - ability to create code directly from diagrams
  • model validation - in terms of complexity, sizing, etc.
Sounds great, but where do I take such tool from? Does your employer provide any license for utilities like that? Unfortunately, my one doesn’t. Maybe I’m a bit odd (hell, I am), but I’ve invested my own private money to buy a professional license of tool named Enterprise Architect (http://www.sparxsystems.com/products/ea/index.html) and I really recommend this one.
 
I decided to pay for the license in 2005, when I was a young analyst asked to prepare some technical documentation for development project of insurance core platform. I’ve asked my supervisor about tools they used for creating documentation and the answer was “Excel and Word”. Obviously, this wasn’t an option for me, so I decided to “go pro” and that’s how I invested in Enterprise Architect. What happened next? Two things:
  1. My documentation was found out as an absolute marvel (people were forwarding it one to another just to show them this “curiosum” ;P)
  2. I was extending my license period of Enterprise Architect every year since that, as it proved itself very useful on many assignments and PoCs.
I didn’t write all of that to convince you that you should spend your own, private money on software your corporation didn’t provide to you. My point was to show the clear (at least to me) benefit of using diagrams in your communication - proper tool is not the cost your project can’t afford.