More documentation isn’t always a good thing.

It’s easy to complain about not having enough documentation, but is it worth writing? It doesn’t come for free.

No one actually wants documentation. What they want is the ability to get things done. Sometimes documentation helps us move faster. But that often isn’t the case.

Risks of Documentation

Writing documentation takes time and is expensive to maintain.

It creates an often redundant branch of information that we must manually keep up to date. Since software engineering is collaborative, you’d need everyone to remember to update the documentation. It’s already hard enough to get one person to remember, let alone an entire team.

That new branch of information is only useful if people read it. Since it’s separate from the code, it’s easy to get lost somewhere. Eventually it will become outdated because it’s difficult to maintain.

If this happens, the documentation wasn’t even a neutral contribution. It was actually overall negative since we wasted time on something useless.

Consider the ROI

Engineers need to think about the ROI of everything they do. Documentation is no exception. Here are some cases where the benefits can outweigh the costs:

1. Documentation that doesn’t change often - We get more value from this since it’ll get more readership over its lifetime and costs less to maintain. For example, high-level system diagrams are often worthwhile.

2. Documentation that many people will need - The impact of documentation scales with the number of people who read it. Documenting a popular API or library is well worth the time if thousands of engineers need it.

3. Documentation you already have - I’m a big fan of writing for clearer thinking. If you already write for yourself, publishing it for others can be worth it since it’s near zero cost with some benefit.

Aside from these, my favorite documentation is inline with the code. It’s much easier to keep up to date and find when needed when it’s next to the code it describes.

Documentation is a hack anyway. All the information is already in the codebase. Imagine one day, you could chat with the codebase and get up-to-date, simple explanations. Given the improvements we’re seeing in LLMs, I don’t think this is far off.

Who wants to manage static documentation that just mirrors the codebase anyway? I’d rather get things done.

If you liked this post, consider sharing it with a friend. As always, you can find more of my stuff here:

• LinkedIn

• Twitter

• Threads

• Youtube

Thanks for reading,
Ryan Peterman