DEV Community

loading...
Cover image for How to write good documentation

How to write good documentation

victoria profile image Victoria Drake Originally published at victoria.dev on ・4 min read

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.

Friday's completed puzzle vs Monday's pile of puzzle pieces. Comic by author.

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:

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 (5)

pic
Editor guide
Collapse
formazione profile image
formazione

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.

Collapse
waylonwalker profile image
Waylon Walker

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

Collapse
mochadwi profile image
Mochamad Iqbal Dwi Cahyo • Edited

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?

Collapse
phlash909 profile image
Phil Ashby

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..

Collapse
paddyhu profile image
Paddy

I found Arc42 and C4 model very usefult to structure my technical documentations.