The art of developer documentation | DigitalBuff

submited by

Style Pass

2021-07-25 19:30:08

Writing technical documentation, probably one of the least favorite things most developers like to do, but equally important as writing code. Let’s see why…

Good documentation solves all of the above problems. Just like a good set of unit/integration tests, it saves you and the team time in the long run.

Let’s start with a cornerstone of good technical documentation, diagrams! A good diagram is worth a thousand words, if it’s a good one… However, many diagrams are just a set of boxes that don’t say anything about how the system works. You see these typically in high-level system “diagrams”.

Don’t make these your go-to diagram type for technical documentation! Don’t get me wrong, these have their purpose when you just want to list features or components of a platform, but generally make for poor technical documentation. So, what’s a good technique to document a software system? That’s where the C4 model comes in.

The C4 model is a powerful way to visualize software systems. It consists of 4 (zoom) levels that allow you to create meaningful diagrams which for each level clearly indicate the systems/containers/components/actors involved and their relationship to each other. I highly recommend reading up on this on the excellent c4model.com site, made by Simon Brown, the original author of the C4 model. Let’s go over each of the four levels by way of example.