Surprising Documentation

Hi,

Class comments, architecture documentation, method comments, API documentation, inline comments, feature documentation, wireframes, entity-relationship diagrams, use-case diagrams, process documentation, end-user documentation…

There are so many things one can document. But what do I really need?

Documentation doesn’t write itself. Someone has to take the time. And for it to truly add value, it needs to be well-written, as complete as possible and focused. Not everyone can do that.

In large corporations - with thousands of employees - a lot is documented. There are software architects who have the time and education to write good documentation. There are so many developers that enough time is allocated to document the code. And technical writers produce the highest quality end-user documentation.

Smaller teams can’t afford this.

Documenting does not seem to add value to the product at first glance. It’s not something the user sees. It’s not something the user uses (except for the end-user documentation).

It’s meant for the developers. For onboarding new employees. For recording decisions. For sorting out one’s own thoughts.

“So what documentation should I write then?”

Write the documentation that is actually read!

“And which documentation is read?”

None that’s outdated. Or documentation that you think might be outdated.

Documentation about classes, methods, and UI elements doesn’t add value. When I read that, I don’t believe it’s still up-to-date. And it’s so quick to check in the code or in the application what the current status is.

Focus your documentation on concepts. Answer the “why”.

• Why were the services divided this way?
• Why do we deploy to these hosts?
• Why was technology X chosen?
• Why is the database not normalized here?

You don’t have to document the obvious. No. Document the surprising. Don’t waste time documenting what everyone knows anyway. You also don’t need to document the advantages of the JVM - you can read that elsewhere.

If you keep surprising the reader of your documentation - then you’ve written down the right things.

Rule the Backend,

~ Marcus