Anyone working on software can speak to the importance of documentation. They will tell you how helpful well-written documentation is, and how they would be lost without it.
However, when it comes time to write said documentation, it becomes a chore. And by the time it is finally done, it always seems to be missing one detail or another.
I’m a firm believer that this can be rectified with a very simple shift in perspective. Instead of looking at documentation as a way of communicating with the next person working on a project, write everything for your future self.
Think of it as a way to keep track of your reasoning, simplify manual tasks, and unload your mental burden.
Documenting as you go
One of the hardest parts of writing good technical documentation is making sure you remember every important detail you are trying to communicate. The easiest way to tackle this is to avoid it entirely.
Instead of trying to write it all up front or recount everything when you are done, write it as you go. Treat it the same as you do your personal notes.
Technical decisions
The best place to start is with your technical decisions. Architectural decision documents are becoming more of a staple of every long-running project.
Although they are increasingly common, it is easy to fall into the trap of treating these documents as a defense of that decision for someone who is going to question you. But this is where you need to reframe it as a note to yourself.
Instead of writing down all the reasons this decision solves the problem, elaborate on what would have to change in the future to invalidate the decision. Write a note to yourself of what other ways you thought of solving the problem, and when those approaches would make sense.
Software is constantly evolving, and more often than not it will be you who feels the pain of your past decisions. That is when it’s helpful to be able to come back to where your mind was at when you made the decision.
And if it’s not you, then you can feel better knowing the person after you will know exactly what you were thinking at the time you made that decision.
Manual tasks
One of the most useful applications of technical documentation is for directing manual tasks.
Developers who have worked on a project for a long time know the feeling of having one task or another that should be automated, but they are going to do it by hand just one more time.
Next time you do a task like this, write down every step you take. When you take this approach, you’re a lot less likely to miss something than you would be if you were to try and write out your process from memory.
Even if this is something you know how to do off the top of your head, it’s always better to assume your future self will come back to it and be completely lost.
You should be writing these steps so that you can run things without even needing to think about it. Once you’re at that point, then you should be able to hand it off to anyone else on the team without them even needing you around.
Production support
Similar to the myriad of random jobs required to maintain a successful long-running system, inevitably things will need to be fixed in production.
If this is a system you’re working in every day, these fixes can be trivial. However, as your attention is pulled away and you lose familiarity with parts of the software, things can get a bit more difficult.
Ideally, these bugs would be things that could be patched permanently, but sometimes things can get a bit more complicated. That is when it’s helpful to document the steps you took to remedy the issue.
When you inevitably come across this issue again in the future you will be able to refer back to what you did last time, or even give someone else the tools to fix things without you ever having to get involved.
This brings me to one of the most important pieces to writing useful documentation. Actually using it.
Use your documentation
You wouldn’t hand off a project to a stakeholder without testing it, so why would the same logic not apply to documentation?
Next time you come across that one-off manual task or production issue, don’t tackle it from memory, even if you think you know exactly what to do. Follow the documentation you wrote, or even better, hand it to someone else and let them try using your docs.
If you find yourself making comments or doing something that you forgot to mention, add it to the documentation. After that, you will have confidence that you’ve covered all your bases.
Reduce the mental load of project ownership
If you find yourself in the position of technical lead on a project, you will quickly find yourself as the subject matter expert of a complicated and ever-expanding system.
As the lead, you are responsible for keeping track of it all, but that doesn’t mean it all has to be in your head.
If you wrote yourself good documentation, then you can let that part of the system go with full confidence that you can pull up your notes and answer any question that might come up.
Now that you’ve successfully offloaded everything you need to know for a project to a collection of well-organized, easy-to-read documents, you can relax knowing you’re ready for anything. Or even better, you can hand it all off to the next person and find the next problem to solve.