The merits of Design Diagrams

You’ll find many articles online describing how to create very detailed design documents covering things like business requirements, data design, UI mockups, class diagrams… Most developers however will shy away from them. Reasons I often hear are:

• "I know what I am developing"
• “I’m not a Technical Writer”
• “Nobody is going to read it anyway”
• “All the info someone would need is in the code anyway”
• “This is going to cost me way to much time and I’m already under pressure”
• “Keeping these documents up to date is impossible”
• “We work Agile, we adapt as we go long, so we don’t need documents”

To make matters worse: often when people do create them, they tend to create very detailed documents confirming their own arguments. So, I want to suggest a type of design diagram that meets the following goals:

• allows anybody to challenge the design BEFORE any development starts
• can be created in < 4 hours
• can be consumed by the reader in < 15 minutes
• saves the team AND the organization time
• allows us to quickly identify those areas that are the most expensive to fix/change (e.g. around performance, stability…)
• is easily maintainable
• ensures that everybody has the same understanding of the design

Note that I didn’t mention creating a design document, I prefer to use the term design diagram. The idea of a design diagram is not to have the full specification written out, but to communicate the essence.

How to create a Design Diagram

Picture yourself explaining your feature to a fellow developer who just joined your team using nothing but a whiteboard. What are the essentials that you will share? Your drawing should show:

• which components are involved
• what each component does
• how they communicate and what the flow of communication is
• what data they manage

With this approach, you’ll end up with something that fits on a single page and can be consumed by the reader in < 15 minutes.

To be clear:

• Don’t describe your code. Add only the high level that is necessary to understand the code. People who can read code, prefer to read code anyway so that documentation doesn’t pay off.
• Don’t write long texts. It is unlikely that you will be able to keep this up to date as your design evolves. Also, most people won’t be willing to read it.

Given such a diagram, I would go as far as to claim the following: If a developer or a team still claims that it takes them too much time, then they don’t have their design under control!!

How detailed you create these design diagrams will be dependent on the maturity of your team and the state of your product/project. For greenfield development with a new team you may require additional diagrams like a class diagram, UML diagrams… For brownfield development with a mature team, one simple drawing may suffice. One size does not fit all!

How does such a design diagram save time?

Here’s how it saves time DURING the development:

• fundamental design flaws can be spotted very early, even before any development has been done
• the design can be challenged with other people very easily and efficiently
• misalignments within the team are significantly reduced
• code reviewers will have to ask less and can ask more focused questions because the intent of the code will be clearer. Code only shows you how something happens, it does not show you the WHY nor does it show you the high-level flow at a glance.
• the chances the organization is not receiving what it expected because of misunderstandings if significantly reduced. This eliminates rework
• testers can identify the weak points easier and focus their testing on the weak points
• …

Here’s how it saves time AFTER the feature is developed:

• Customer Support people who need to analyze a customer defect, can better understand the design and therefore better direct their analysis
• Trainers can better understand the inner workings, and this can benefit their training
• Developers who need to change or extend this feature 12 months from now can better understand how it was designed, why it was designed this way and how their changes fit in the design
• The Scrum team that created this feature will have to explain their intent/design less
• …

Fixing a bug in production is expensive, but – once the bug has been found – fixing a small code issue may not be too bad. The expensive bugs are the ones where the design was flawed from an architectural perspective impacting performance, availability, runtime cost, scalability…. Those are the ones requiring a severe refactoring. Luckily, very often, these can be identified by just looking at the design diagram!

Give me an example!

Imagine the following example: suppose we have an e-commerce site in which customers can write reviews about our products. So far, we have been reviewing these comments manually but our site became so popular that we can't process the load anymore, so we want to automate this process more.

Every time a review is added to a product, we want to analyze automatically whether it is a positive or a negative comment. Products that got too many bad reviews are then flagged accordingly so that our product managers are made aware of this.

A design that could be proposed by the team for such a feature is this:

I will not claim that this design may be the ideal solution for this problem, but it does already show me some essentials:

• I can clearly see the order in which all operations are done
• I can assess the performance of this solution
• I can see potential problems with rate limitations in Azure Machine Learning
• I can start to estimate the run-time cost
• When I or somebody else needs to review a pull request for this feature, we can better judge the code because we now also know its intent and how it will be called.
• I can see in which data store which information will be persisted
• I can see that we will be able to configure the sensitivity
• And when I want to ask additional questions, I can make them very targeted and clearly highlight which component I am talking about to avoid any confusion!
• …

There is a lot that I can learn from this very simple diagram that has very little text and that I made in PowerPoint in under an hour.

Which tools you could use

You don’t need expensive tools to create design diagrams. Here are some tools that I sometimes use:

• PowerPoint
• https://www.draw.io
• https://www.websequencediagrams.com

Two things are important:

• Use tools that everybody in your organization has access to. Everybody in the team should be able to create or modify a design diagram.
• And always make design diagrams digitally. People should be able to extend or adapt the design diagrams as the project evolves at any time.

When to create them?

If your feature involves multiple components, multiple services, a complicated algorithm, remote calls… a design diagram should be created.

Create a design document BEFORE any development starts. The sooner you have the document, the sooner you can reap the benefits. Only creating a design document after the development means that you lose many of these benefits.

And in case you are wondering, no this does not smell like waterfall. Working agile does not mean that you shouldn’t think about where you are heading upfront.

Who should create them?

For more mature scrum teams, it is the team developing the feature that should create the document. For less mature teams, there may be an architect preparing the designs for them to get them familiar with the thought process, but that should not be a permanent solution.

Conclusion

The key thing I want you to take away from this article is this:

1. motivate people to create designs upfront, but don’t expect detailed documents. Find the thing that brings you the biggest bang for the smallest buck
2. don’t try to cover all risks with documentation but do cover those risks that would be the most expensive to fix
3. “a picture is worth a thousand words” very much applies here. A well thought drawing with the right level of detail, is worth gold!