If you’ve ever half-written a software project before taking a few days off, this is the article you’ll discover you needed when you reopen that IDE.
In the technology teams I lead, we make a constant effort to document all the things. Documentation lives alongside the code as an equal player. This helps ensure that no one needs to make assumptions about how something works, or is calling lengthy meetings to gain working knowledge of a feature. Good documentation saves us a lot of time and hassle.
That said, and contrary to popular belief, the most valuable software documentation is not primarily written for other people. As I said in this well-received tweet:
Victoria Drake@victoriadotdev
The secret to good documentation is to write it while you're writing the code. You are your first audience. Explain what you're doing to yourself. Future you will thank you!15:46 PM - 24 Nov 2020
With holidays around the corner, it’d be prudent to prepare for the possibility of some eggnog-induced programming paralysis. (Pecan pie and Python make a great combination.) 🥧🐍
Here are three concrete steps you can take to write good documentation before it’s too late.
1. Start with accurate notes
As you work out ideas in code, ensure you don’t soon forget important details by starting with accurate notes. While you will want to explain things to yourself in long-form later, short-form notes will suffice to capture details without interrupting your coding session flow.
Keep a document open alongside your code and write down things like commands, decisions, and sources you use. This can include:
- Terminal commands you typed in
- Why you chose a particular method over another
- Links you visited for help or cough_copy-paste_cough inspiration
- The order in which you did things
Don’t worry about full sentences at this point. Just ensure you accurately capture context, relevant code snippets, and helpful URLs. It can also be helpful to turn on any auto-save option available.
2. Explain decisions in long form
The ideal time to tackle this step is when you take a break from coding, but before you completely go out to lunch on whatever it is you’re working on at the moment. You want to ensure that context, ideas, and decisions are all still fresh in your mind when you explain them to yourself.
Go over the short-form notes you took and start expanding them into conversational writing. Be your own rubber duck. Describe what you’re doing as if you were teaching it to someone else. You might cover topics such as:
- Quirky-looking decisions: “I would normally do it this way, but I chose to do something different because…”
- Challenges you ran into and how you overcame them
- Architectural decisions that support your project goals
Stick to the main points. Long-form writing doesn’t mean you’ll be paid by the word! Just use full sentences, and write as if explaining your project to a colleague. You’re explaining to future you, after all.
3. Don’t neglect prerequisite knowledge
This step is best done after a long lunch break, or even the next day (but probably not two). Re-read your document and fill in any blanks that become apparent after putting some distance between yourself and the project.
Take extra care to fill in or at least link to prerequisite knowledge, especially if you frequently use different languages or tools. Even an action as small as pasting in a link to the API documentation you used can save hours of future searching.
Write down or link to READMEs, installation steps, and relevant support issues. For frequently performed command-line actions, you can use a self-documenting Makefile to avoid having to man common tasks each time you come back to a project.
It’s easy to forget supporting details after even just a short break from your project. Capture anything you found helpful this time around.
Document all the things
The next time you catch yourself thinking, “I’m sure I’ll remember this part, no need to write it down,” just recall this emoji: 🤦♀️
Software projects are made up of a lot more than just their code. To best set up your future self for success, document all the things! Whether it’s a process you’ve established, Infrastructure as Code, or a fleeting future roadmap idea — write it down! Future you will thank you for it.
If you enjoyed this post, I'd love to know. Join the thousands of people who learn along with me on victoria.dev! Visit and subscribe for more about building your coding skill stack.
Discussion (6)
I think the most pragmatic and useful ideas for documentation as of today are:
Heavyweight forward engineering , ie CASE tools, UML etc have been skipped as newer engineers jump into agile and hacking code fast and a few years later we are now having issues with maintaining codebases and building big systems.
Reverse engineering ie code back to diagrams was an emergency measure and gave some assistance.
Living documentation is a great idea but tools are not quite there yet but I am hopeful, they need to be easier to use and more consistent, but I feel this will be the next pragmatic step.
I agree with everything, make the documentation while you are coding is so easy to do and, instead, so hard to make after some days, so this is the best advise if you do not want to solve the same problems again and again from skratch, instead of saying... oh, that's how I did it and move on to solve new problems, not old ones.
A good concise readme can go a long way for handing off a project, or being handed a project. Without that its hard to see the forest from the trees.
Go forth and document all the things
Does coding documentation is violates clean codes?
How to encourage our teams to write documentation also to avoid excuses similar like below.
"Clean code is code without comments" or sometimes "We don't have time to create UMLs & diagram also the software spec docs" etc so on
Please any suggestion or advice?
Something I've seen work is supporting people to change teams, they get to experience the newbie ramp-up more often and appreciate good docs, rather than living their own codebase for years and becoming the single point of expertise..
I found Arc42 and C4 model very usefult to structure my technical documentations.