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.
Top comments (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.