Effective Sketches

On Thursday I was at Simon Brown's Effective Sketches session at Skillsmatter. Just because my pictures are pretty awesome doesn't mean there's no opportunity for continuous learning.

The points Simon made in the session really made sense to me, and I wish I could have had something like that as a primer when they taught us UML at university. Without the context of what the diagrams were supposed to mean, to convey, all the boxes and lines made no sense to me back then. I'm still not a fan of large chunks of UML because I think the convention sometimes gets in the way of real meaning.

My take-away points were:

  • Don't try and squidge everything onto a single diagram. The reason lots of different flavours of architecture diagrams exist (e.g. logical view, infrastructure view, etc) is because you have different audiences for each of the diagrams and different things that are important when you're looking at it from one particular angle.
  • One diagram you particularly need, especially if you are producing a stack of documentation for a system (e.g. you're a consultant presenting findings to the client) is a really succinct, summary view of what the system is actually trying to achieve.
  • If you're not going to use UML, you should at least agree on consistency and some conventions - for example, does the direction of an arrow represent data flow or dependency?
  • UML tools make it easier to represent different views of a data model and retain consistency. One diagram is less likely to contradict a different view if your sketching tool points this mistake out to you.
  • Yes, your code should be self-documenting. But you can't give the code to your business customers or expect your hardware guys to figure out your requirements from it. To pass knowledge around the business it's more efficient to have diagrams representing the shared understanding of the domain.
  • Architecture diagrams should show the intent and the vision of the system.
I also used my laptop to take notes for the first time. In the past I've preferred not to use a laptop, because a) I like pencil and paper and it allows me to doodle and b) the temptation to read my e-mail or check facebook is not something I want to succumb to. But using Evernote really worked for me, I could annotate the slides with my notes, and it made converting my notes into this post a lot easier.

PS it has not escaped me that this is one post without a diagram. The irony is not lost on me.


  • Trisha Gee

    Trisha is a software engineer, Java Champion and author. Trisha has developed Java applications for finance, manufacturing and non-profit organisations, and she's a lead developer advocate at Gradle.

    View all posts