Why developers should write documentation

Have you ever had difficulty getting developers to document their code?

I work with all kinds of developers. While some of them are keen, talented writers, others won’t document without… convincing… that:

1. Yes, developers should write documentation.
2. No, code-level documentation isn’t enough.

We value working software over comprehensive documentation

A developer once met my documentation request with a dismissive reference to this part of the agile manifesto that says that agile shops value “Working software over comprehensive documentation”.

The developer in question conveniently omitted the part that says “while there is value in the items on the right [comprehensive documentation], we value the items on the left more [working software].”

Documenting in an agile environment means producing just the right amount of documentation that adds value to your product or organization.

There’s little debate that end-user documentation adds value. But developers benefit from technical documentation, too. Technical documentation is a good investment of your effort when it:

• Facilitates knowledge transfer when a feature’s main contributor is out of the office or leaves the company.
• Tracks design decisions and their rationale so that development teams don’t duplicate the analysis effort later on.
• Empowers developers to troubleshoot production issues on a system that they didn’t implement.
• Keeps track of the dependencies between components of a feature or service.
• Empowers developers to maintain a feature or service that they didn’t implement.
• Reduces new employees’ learning curve.
• Helps developers understand a feature that has been shelved for some time more quickly.

Anyway, I write clean, self-documenting code

Some developers argue that they don’t need to write any documentation at all, because they write clean, self-explanatory code.

But code is only one layer of technical documentation. Documentation at a higher layer of abstraction helps other developers understand the code more quickly and guides them through the navigation of a large code base.

The following technical documentation complements code-level documentation, whether that means comments or self-documenting code:

• A readme file that tells new developers how to install a piece of code and set up their environment for a smooth start.
• A components diagram that illustrates what components a feature or service comprises, and what external components it integrates with.
• Where a developer should start when they read the code for the first time.
• In what sequence an external component should call your API endpoints to complete a common use case.

What do you think?

Let me know in the comments if you have other, better justifications why technical documentation matters, or if you don’t agree.