5 Reasons to Write a Document Before Writing Code
Writing a proper design document is often frowned upon. Whether it is an RFC or a problem specification — it doesn’t matter what you call it — the usual reaction is:
Ain’t nobody got time for that. We need to write code.
But it can be highly beneficial, especially once the company reaches a certain size and product complexity.
Let me give you 5 reasons why.
Reason #1: It forces you to structure your thoughts
As engineers, we have all been there. We have an algorithm in our mind which solves the problem perfectly. Perhaps we have even discussed it in the team. It seems dead simple and straightforward. Then we start writing code and suddenly it is not that simple anymore! There are many edge cases and the original idea may not work at all.
Now consider a problem which requires more than just a hundred lines of code. It could be thousands. Or it can affect multiple components owned by independent teams. Discovering design flaws late in the development process can be very expensive (and frustrating).
Here is the thing: Putting thoughts in words is a useful process on its own. It slows down your mind and forces you to clarify your ideas and intentions.
Also, you ultimately write the document to explain to your colleagues what you want to do. And you can’t explain something unless you really understand it.
Writing a comprehensive design document before you start coding forces you to fully understand what, why and how you want to do that.
Reason #2: It allows for early reviews
We all understand why code reviewing is great. But then again, what about problems which exceed a single merge request?
Let me extend the previous point: a design document is a great opportunity to explain to your colleagues what you want to achieve in a structured way. Once you do that, they can review it! They can poke holes into your design. They can find flaws, inefficiencies, poor decisions.
All of that before you start writing any code and potentially waste time.
Reason #3: It forces you to defend your decisions
When you write code, there is rarely time to really get into why you are doing what you’re doing. Ideally, you should write good merge request & commit messages with some reasoning and your reviewers should challenge that, just like they should challenge every single line in your MR. But that can hardly leave the scope of a single MR and at that moment it is usually way too late to ask questions like why you are calling that particular API endpoint.
A design document will allow you (and should actually force you via reviews) to deeply think & justify all your decisions. It is an opportunity to write down what the actual problem is and defend why you think your solution is the best.
Then again, good reviewers will make sure that you don’t go off the road with your thinking.
Reason #4: It can broadly communicate what you want to do
For efforts spanning multiple teams, having a design document is basically a necessity to get everyone aligned. But it can be immensely useful to share it even with folks who are not in the scope:
- there may be somebody at your company who has solved something similar and they can help you,
- or there is somebody who is doing exactly the same and then you should perhaps join your efforts,
- or maybe there is somebody who happens to have that crucial piece of information that will change the whole direction of your project.
Sharing the right amount of information within companies and keeping everybody informed but not overwhelmed is hard. Having nice documents for all changes & decisions with a tl;dr at the top can help greatly.
You can take your document and paste it in the Slack channel where you believe the audience may be the most interested. The majority of people will ignore it, a few will read it. Even fewer will contribute but then their contribution can be that very crucial piece of information that you need.
Reason #5: It documents decisions & mechanisms
Often you may be wondering why certain things are done the way they are. It may seem stupid. Or you may be wondering how something works. But you just don’t know and there is nobody to tell you because nobody remembers or the relevant people are no longer at the company.
Ideally, you’d find that information in the documentation. But the thing is that writing documentation and keeping it up-to-date… well… ain’t nobody got time for that… like really.
And that’s why design documents are so useful. They can be the documentation. If the document is supposed to be worth it (like contain the proper explanation and justification of the intention), it usually needs to start with the current state and then describe the new state. And well, that’s all you need. If all big decisions and changes have a proper design document, you just do a little backtracking and you should get a good idea of how things work and why.
Final words
Think of writing documents as of writing code. Just on a higher abstraction level. It’s all there. You are transforming your ideas into a structured, written form which is reviewed by your fellow engineers and which sticks around so that other people can check it.
One last thing: design documents, in order to be useful, need to be good. Just like code. So dedicate the same amount of effort to writing nice documents as you’d dedicate to writing code. There will be a second part to this blog post which will share some useful writing tips.
FAQ
- Does this mean that I should always write a design document?
That depends but generally speaking, this blog post is trying to make the point that you indeed should. But keep in mind that a good document can be just three paragraphs of text. - Does this mean that I shouldn’t write any code before I write a document?
Of course not. You are free to prototype & experiment as much as you want. But you should do it before you start writing actual production code.
