Improve your communication skills with expert diagrams

If you’re a developer who wants to contribute to the big picture — the high-level design of the systems you work on — you need to be able to communicate your ideas clearly for your peers to understand. In my experience, with myself included, developers are inherently lacking in this skill.

Fortunately you don’t need to spend years working on muscle memory and instinctive reflexes. You just need a framework for creating clear diagrams at the appropriate level of detail. Fortunately again, such a thing exists, and the skills are quite easy to come by so I’d love to help you.

In this post I’ll try to convince you that the small efforts of learning and creating diagrams can have a big impact on your team, your company and your career. In the next post I’ll show you how easy it is to create effective diagrams.How do you know my diagram skills need to be improved?

Having attended Simon Browns architecture for devs workshop, I failed to provide a set of diagrams clearly expressing the design of a system. Then same was also true of the other engineers and architects in the room. 

Just recently I ran a customised version of the diagrams workshop in the offices at 7digital for a few of my colleagues. Again, whilst having lots of fun, I noticed the challenges faced by developers to find the appropriate diagrams at the appropriate level of detail with well communicated notations. 

You might be different, but that’s 100% of developers so far (including myself) whose skillset would be much improved with greater ability in this area.Diagrams are a fantastic way to share knowledge

A former colleague made me laugh once, “shut up and show me the diagrams” he said. And for my money he’s absolutely right. When you’re talking to me, explaining how a system works, I’m too busy creating a mental image and trying to keep up with you. 

Given the option, a lot of times I would much rather you show me a diagram first so we can base our conversation around that. Maybe I’m different to you, though? 

Even when talking to non-technical people you can aid communication substantially with diagrams. It’s incredibly easy for us developers to talk in complete tech waffle. Yet when introducing diagrams at the right level of detail, I have seen how greatly-enhanced business-developer communication can be. 

Diagrams can even be useful within or between developer teams. Often you’ll see new starters given a code base with another developer speaking a foreign language in their ear about how the system works. Maybe even a few ad-hoc diagrams if you’re lucky. 

I’m sure you can relate to this — being the new starter and having difficulty taking in all the new knowledge. I blogged before about how I’ve attempted to alleviate this problem with the use of proper diagrams. 

I think diagrams can have an even greater role. I want all development teams within an organisation to have a few key diagrams. This, I believe, would result in more knowledge of how the system as a whole fits together, amongst many other benefits — not least the ability to coordinate teams and move developers between them with greater returns on productivity.Diagrams encourage you to think about important decisions earlier and keep an eye on risks

Transforming requirements into a working system almost always involves a lot of significant decisions that can drastically affect the success of a project — Solr or Elastic Search, SQL or NoSQL, message bus or http, distributed architecture or monolithic app. 

Some combinations of choices are better suited to your expected business use cases. By having a few diagrams that show these relationships you will often see the potential for pain, and avoid it before you have even started coding. Remembering the cost of change increases the longer time goes by, the potential here is massive. 

If you are a fan of “fail fast” diagrams are your friend.

Important, too, is ensuring all requirements are met — functionals and non-functionals (such as scalability, security etc). With good diagrams, you get a visual model of the system you can walk through and apply use-cases against. With a wall of text we rely on mental representations, which I find to be a much poorer tool for collaboration.Diagrams and DevOps

One of the big buzzwords at the moment is DevOps. If you’re a fan of systems thinking, attempting to optimise the whole rather than just individual parts, then you’re probably loving the DevOps culture 

Part of DevOps is bringing developers and ops guys closer together. This involves transitions such as inviting your ops team into the design stage of your project. Sharing and collaborating with proper diagrams could be a massive help here.

stolen from http://dev2ops.org/2010/02/what-is-devops/  Think about this example: you’re a .NET shop and want to run parts of a new system on linux; in the process introducing chef for configuration management. 

Is it best to create a design expressing these features, and share it with the ops team? Or is it best to churn out the code and find out sixth months later that for any number of reasons your ops team can’t allow that, or they had knowledge of a much better alternative? If you rely on talking, it can be hard to express all of the details that can make this difference. 

With a design, you can get a rough estimate of the hardware you’ll need. The systems team can tell you if that is sensible, feasible, and how long, if possible, it would take them to acquire and prepare it.Bring these skills to your team

I’ve now outlined why I think proper diagrams are an important communication tool, not just between developers, but amongst the whole business. Addressing this problem, then, in the next post I’ll share a few of the tricks I’ve learned for creating excellent diagrams. 

If you’re keen, you can learn from the man himself by attending Simon’s workshop or reading his book…. 

… however, if that’s not possible (for whatever reason) I’d love to help your team acquire these skills. I can help you run an architectural diagrams sessions, customised to your situation if needed. 

I’m not looking to make money, so there is no charge. It’s just a great opportunity for me to learn from other developers, and help them acquire highly-important skills. Email me at nick [at] ntcoding.co.uk