Please write your technical documentation
Apparently, everyone decided that the technical documentation was bullshit and useless. It’s driving me crazy. You and I need to talk about this.
I have no time to write technical documentation
Time? You’re telling me you don’t have time for your documentation? Okay, let’s talk about time. Do you know how much time you’re wasting for everyone ? How much time you’re wasting for yourself ?
If you build a library or an app, it will potentially be used by a lot of people. Or at least by yourself. The time you save now by not writing your technical documentation, you’re wasting it exponentially in the future. Okay, let’s take a concrete example.
A few years ago, I was in a company where everybody was pushing code on the same dev server. Everyone was also testing change on the same server. Hell on earth. So I made a local work environment for the team. Concretely, I simulated the production in a giant docker-compose with all the microservices, database, cache and volumes for the data. It worked on my machine. Ship it, it’s perfect like that.
Obviously zero documentation. No requirements. Nothing. Because reasons.
- First, of course, i was lazy.
- Second, I spent time on the environment itself, so I might as well save some time on the documentation.
- Third, I thought it would allow those who don’t know anything about it to familiarize themselves with docker-composer and how it works.
That was a bad idea.
Soon, I started getting e-mails full of the famous “it doesn’t work”. Especially from newcomers. I spent days explaining how the docker-composer worked, the requirements and how to work with it. I cried blood and ended up doing a huge amount of documentation. The complete setup time went from one day to several minutes after the documentation.
Documentation makes people autonomous and allows you not to be disturbed in your work. The time saved by your company is phenomenal. And it works for everything, everywhere. It’s the same scenario every time. Your time-saving argument is invalid.
Okay, but I don’t know how to write technical documentation…
We’re talking about technical documentation, it’s not Shakespeare. You don’t have to be a writer to be read. All it takes is content helping people. And your technical documentation will tremendously help people.
You don’t know where to start? Very simple, here are the MANDATORIES sections.
- Introduction
A few lines that explain the why of your work. Super important for a user who just wants to know quickly if you stuff is usable.
- Dependencies
What are the dependencies and how to get them ? If you don’t put this information upfront : your library is broken for everyone. No one’s gonna have the patience to figure out why it doesn’t work.
- Quick start
The command sequence or code snippet that allows you to quickly use the library. Same that before, without this nobody will take the time to understand your stuff.
- Notes
Maybe the most important part. Here you put all the hacks or informations people need to know so they don’t have any problems. If there’s any technical debt, just come clean and talk about it here.
Obviously this is the bare minimum. We’re at level zero. We’re at level : “I don’t want to do it, but I’m doing it anyway”. With this level of documentation, if your library is good, you will have people using it. And the code has to be perfect.
My code is perfect! No need for technical documentation
If you come across a library with zero documentation on GitHub, are you’re gonna use it ? No. You’re not going to spend time looking at the code, function by function, to see if it’s well coded and if it suits you.
You’re going to close the tab and you’re going to continue your research. It’s exactly the same with your own library. Your rockstar code is useless unless it’s documented.
Why is it so important that you write a minimum of documentation about your work? If your library doesn’t have technical documentation, your library doesn’t exist. You’re a rock star, your code is perfect and your application is revolutionizing the world? Who cares ? Where’s the doc ?
I’m not done with my library, so no technical documentation.
It’s not a question of whether it’s over or not. People are gonna use your library as is? And yes, that question includes you. If so, then you need documentation. It’s when a library is not finished that it needs documentation the most. Explain what works. Explain what doesn’t work. In fact, mostly explains what doesn’t work. Explains what’s going on. Things that will save time.
Story time. A long time ago in a galaxy far, far away, I worked with an internal cloud product. Of course, you guessed it, there was no documentation. I had no choice. Plus i needed to ship it fast. I’ll pass all the details, I’m doing my little API and I want to push a first version. Immediately, timeout in the pipeline. No log. No idea what’s going on. Black screen.
Of course, git blame. I find the name and the dude’s not here today. Well yes, otherwise it’s not funny.
So I start trying a billion things. Different ways to make my API, put logs everywhere, send an empty API. Timeout, it doesn’t work, and that for hours.
Desperate, I start looking at all the source code of the project. It’s a huge fucking gas machine. And then I found a bash file hidden in the middle of the pipeline process. It returns false if it doesn’t find a route called /status. Just wrong. No log. No errors. False. If I’d have known that right away it would have lasted five minutes.
The minimum technical documentation is the documentation of the technical debt. Not doing this minimum is a phenomenal waste of time. The laziness of not documenting cost your company a lot of money. And it’s all your fault. Not to mention the fact that the other developers are going to hate you. If you’re going to take someone into a minefield, at least give them a mine detector. They’re gonna love you for that. And most importantly, they’re gonna come back alive.
Not happy? Don’t use my code!
But I don’t have a choice! You’re producing an in-house library. As I told you earlier if it was open-source I wouldn’t even look at your library. I would’ve even found it, actually.
Also the documentation you write it not only for others. As Damian Conway says, “Documentation is a love letter you write to your future self”. In a few weeks, when you’ve forgotten everything you were doing on this project, you’ll save yourself a lot of time.
Respect your colleagues. Send them love. Allow them to be completely self-sufficient. Allow them to move fast because of you. Save your company an incredible amount of time. Save your company money. Make sure that your co-workers aren’t going crazy. Become a team player. Respect yourself. Allow yourself to go fast. Send love to your future self. Write your damn technical documentation.
Epilogue
I feel better now. I enjoyed our talk. I’ll try not to freak out so much next time. I had to tell someone. If you run into another dev, talk to him about it. If everyone starts documenting their code, things will go faster.
