Software development as a profession has changed rapidly over the last 20 years. We have gone through major shifts such as cloud, test-driven development and container-based technologies, to name a few. But little has happened around how we actually document our solutions and our architecture. Maybe it’s because it’s seen as boring? Something you only have to do at the end of the project because it’s agreed. At the same time, we know the importance of effective documentation of a solution. Not least for a long-term functioning management, or for that matter for you to understand a solution three months later.
But let’s take a step back. What do you mean by documenting a solution?
VISUAL VS. TEXTUAL DOCUMENTATION
When we think of documenting a solution, many of us probably think of filling in a Word document. If you are really lucky, there are a number of predefined headings you can fill in.
But there are few things as mentally exhausting as opening a more or less blank document, knowing that you need to spend hours filling it in and that it will then most likely not be read by anyone…
If instead you imagine that you have to describe a solution to a colleague in the simplest possible way. Most likely, you will not start with text. You will probably stand in front of a whiteboard and start drawing boxes with simple arrows in between. Visual diagrams are by far the most effective way for us humans to communicate complex contexts, including when describing solutions and architecture.
So why don’t we use diagrams more often to document solutions and architectures?
DIAGRAMS AND NOTATION
One of the reasons we haven’t historically made more use of diagrams to describe larger architectures and solutions is that it’s quite simple to start with. But it gets complicated after a while. Without a model and a notation, it quickly becomes messy and difficult to follow.
The Unified Modelling Language (UML) is familiar to many. It was a solution to the above problem, describing a notation for when different boxes, shapes, arrows, arrowheads, colours etc. should be used and what it should mean. The problem with UML, however, was that as a notation it quickly became complicated. There are week-long courses aimed at just learning UML, something most of us felt was wrong and were uninterested in.
The C4 model consists of a number of levels of diagrams where you start by describing larger contexts that you can then zoom into. In addition, the model contains a very simple notation that more or less just describes how to use boxes and arrows between them. In many ways like how you would draw a solution on a whiteboard. The model has become very popular worldwide and more and more organisations have adopted it to describe their solutions and architectures.
ADVANTAGES OF THE C4 MODEL
At Kazoku, we have increasingly embraced the C4 model. It allows us to document a solution quickly and effectively. The different levels of the model also give us a greater opportunity to communicate with both technical and non-technical users of the solutions we create.
Software documentation has historically focused on technical details and has mainly been intended for developers. Understanding the big picture, how everything fits together, has often been the preserve of few. The C4 model makes it possible for all interested parties to see how the different solutions actually work together and how the solution flows within the organisation.
For us at Kazoku, it is important that both our employees and our customers feel that we are using their time as efficiently as possible to achieve the best results. The C4 model is the most efficient way we have found to document solutions.
TOOLS FOR C4
We have chosen to work with Revision to document our solutions. Revision fully supports the C4 model and at the same time allows us to quickly and securely share our diagrams both internally, within the project and to other stakeholders. With Revision, we create an accessible and efficient hub for our documentation. From the hub, we can then share documentation to different applications and platforms. Revision has several built-in features to share diagrams effectively.
INTERESTED IN HOW YOU CAN DOCUMENT YOUR SOLUTIONS?
We at Kazoku IT are incredibly pleased that we chose Revision as a tool for documentation, and so are our customers. We are very grateful to have finally found a tool that simplifies documentation. Are you also interested in Revision? Contact us at richard@revision.app or visit https://revision.app/ for more information.
