Diagramming Tips for Tech Leads (Video)

01-19-21 Gary Tempus

Learn to effectively communicate software design and evolution through diagrams, which can help you align different visions and focus the team on what’s next.

We have all attended a planning meeting that is plagued with confusion. Questions arise about the proposed software design or architecture updates and often spill into uncertainty of the system’s current state. On any sizable system, each team member’s mental model is likely inconsistent and out-of-date. Discussion is absolutely necessary to keep things from getting out of hand.

As a result, much of the sprint planning time is misspent trying to reestablish a consistent context from which to build upon. For larger teams, this can cripple productivity at the beginning of a sprint as inaccurate communication amongst the team causes process loss.

Aside from acknowledging the barrage of questions clarifying the team’s mental models, a wise tech lead is sensitive to body language during planning sessions. Are previously engaged devs starting to get that blank stare? Is everyone agreeing all of a sudden on several disparate topics? In these instances, I begin to suspect that the team is succumbing to entropy. In other words, maybe some team members had great ideas coming into the meeting, but after hearing all the confusion surrounding the state of the system or application, they begin to surrender to such maladies as groupthink and pluralistic ignorance. They may be afraid that they’re “not getting it” and don’t feel comfortable continuing to ask qualifying questions during the planning session.

This can be remedied, of course. Diagramming often helps expeditiously align all those awesome mental models and focuses the team on what’s next with clarity and confidence. This is the feeling we all want coming out of a planning meeting. I incorporate the bulk of my diagramming as a pre-planning activity one or two sprints before they are needed. Many diagramming tools exist, but I’m currently using diagrams.net.

Ready, Set, Draw

An intentional diagram, careful to address a specific context or series of events, is extremely valuable—whereas an ill-conceived diagram akin to the proverbial gordian knot will only cause more confusion and frustration. Here are several tips for slicing away the complexity of interesting software projects, getting quick team alignment, and enabling a valuable exchange of ideas during your next planning session.

Context, Context, Context

Representational consistency means knowing how all the parts relate to the whole. To get everyone zoned in and focused on the area of interest within our system, I always try to start with a big picture. Obviously, it only needs to be broad enough to tell the story of the upcoming sprint, but you get the idea. I’m most likely not going to show the architecture of the entire enterprise if we’re clearly working on some frontend changes for a web application we worked on last sprint. On the other hand, it’s equally important that I not start the discussion zoomed in on a fraction of a RESTful payload either.

Know Your Tools

Decide on a diagramming tool and stick with it for a time. There are several tools to pick from. I am currently satisfied with diagrams.net. You don’t have to master every single feature: just be very comfortable with the subset that you have currently adopted. Living diagrams are useful for a longer period of time than static drawings. With that in mind, knowing your tools well will result in a much less frustrating experience for you and the team when small updates or additions happen during a group discussion. Knowing the shortcuts for frequently used features and being familiar with the various artifacts’ idiosyncrasies when in “edit” mode will go a long way to maintaining a relaxed planning session.

Spirit of the Whiteboard

Larger changes, of course, should be made outside of meeting time. However, I still like to capture our group mental model in some low-fi way. Historically, this has been at a whiteboard or erasable surface. However, even before our entire team had to be remote, it wasn’t very inclusive of the attendees that were remote. Pointing a camera at the whiteboard was about the best we were doing for those folks. It’s not great. I’ve been the remote person on some of those meetings, and it’s tough.

I’m currently experimenting with an inexpensive drawing tablet that I keep handy for just such occasions. You can put diagrams.net in ‘freehand’ mode and then get your art on! It’s not perfect, but it’s much faster than capturing brainstorms with the drawing stencils. And everyone gets to see the updates with clarity (and make fun of the artist).

The whiteboard feature in Zoom also comes in handy and works well with my drawing tablet. By keeping the tablet always connected, I find it handy to switch over to the whiteboard and start jotting down the big ideas. And I have the added benefit of still getting everyone’s immediate feedback.

Incremental Builds

Nope. You didn’t just slip into a continuous integration article. Incremental builds are a thing when presenting information too. I came across this term in Fundamentals of Software Architecture by Mark Richards & Neal Ford. The authors explain that showing all of the visual information for a concept at once can result in a rather dull presentation. Rather, building up the story can keep the audience engaged.

For planning purposes, I use incremental builds to tell the story of what is going to happen during the next sprint. Frequently, the team has an idea of the changes or additions we’re going to make during the next iteration. However, I like to start with what design or architecture exists now and then gradually roll in changes using layers as we discuss them.

Layers, FTW!

The “layers” tool is what I use to reveal and incrementally build up my diagrams. Give the layers meaningful names. You’ll thank yourself later, and it also makes navigating the diagram much easier for other team members who refer back to the diagram when exploring on their own or implementing a story. Getting too clever with your layers will cause you to tie your incremental build in knots and discourage other folks from referring back to the diagram. Give the layers good domain names, arrange them in a logical order, and try very hard to make the artifacts in the layers represent a cohesive unit of work. In other words, don’t make folks go hunting for all the far stretching places the drawing has changed.

I cannot emphasize how effective the use of layers can be when discussing a system change. Akin to what Gojko Adzic describes in his book Fifty Quick Ideas to Improve your User Stories, being able to describe (and in our case, show) just the changes that need to be made enables the team to agree on the scope and effort of a story in record time and with confidence.

Get Out the Map

As mentioned earlier, the planning meeting is not the place to start the next diagram additions for the sprint. Diagramming is solidly a pre-planning activity for one or two sprints before diagrams are needed. This gives you, the tech lead, time to discuss the various stories/epics for those sprints with stakeholders. It allows time for you to solicit feedback from the team in relaxed brainstorming sessions with smaller groups or one-on-one with relevant lead devs. Just as we don’t want to come into a planning meeting with empty cards and attempt to create, vet, and make them work-ready all in one planning session, I also don’t want my diagrams to be a complete surprise. Again, each member will have a mental model; we want to get everyone synced up as quickly as possible so we can start planning our sprint with work-ready cards that everyone is eager to start implementing.

Well-crafted diagrams are one way we can accomplish this. Give your team a map to navigate through our increasingly complex software projects. Paired with the other essentials, such as well authored stories/cards, good diagrams will improve your team’s confidence in their knowledge. This will lead to better discussions and will alleviate the “two steps forward and one step back” feeling a tech lead can have when describing where the software or system is being asked to go next.