Fordel StudiosThere is an engineer on your team who writes documentation. Real documentation: clear setup guides, architecture decision records, runbooks that actually work, API references that do not require reading the source code to understand. Every new engineer they onboard gets up to speed in a week instead of a month. Every engineer they work with stops getting blocked on "how does this work."
This engineer is doing their job and half of yours. Their performance review probably does not say so.
The Economics of Documentation
Documentation is a force multiplier. A setup guide that takes four hours to write saves every future engineer two days of confusion. An architecture decision record that explains why the codebase uses event sourcing saves every new hire a week of misunderstanding. A runbook that accurately describes how to respond to a specific alert saves on-call engineers from reinventing the solution at 2am.
The engineer who writes these things is not doing soft work. They are doing high-leverage engineering work. The problem is that leverage is invisible in most measurement systems. You can count PRs merged. You can count bugs fixed. You cannot easily count "blocks prevented" or "ramp-up time saved." So you do not count it, and the engineer who creates the most invisible value gets evaluated on their visible output instead.
“Documentation is the engineering work that keeps compounding after the engineer who wrote it leaves. It is the closest thing to a gift that one engineer can leave for all future engineers.”
Why Engineers Stop Writing It
Engineers stop writing documentation when they notice it does not affect their performance evaluation, when they observe that engineers who do not write docs advance at the same rate, and when they internalise the cultural message that "real engineering" is code, not prose. The culture teaches them to stop. Then the culture complains about the lack of documentation.
The other reason is that documentation is genuinely hard. Not technically hard — hard in the way that teaching is hard. You have to understand something well enough to explain it to someone who does not share your context. Most engineers find this uncomfortable because it reveals the gaps in their own understanding. It is easier to write code that works than to explain why it works the way it does.
What to Change
Make documentation a first-class deliverable. A feature is not complete without a documentation update. An architectural change requires a decision record. An on-call incident requires a runbook update. These are not optional. They are part of the definition of done, enforced in code review the same way tests are.
Recognise the engineers who do this well. Explicitly. In the performance review, in the team meeting, in the conversation you have about who should be promoted. The engineer who writes documentation well is usually a better teacher, a clearer thinker, and a more reliable long-term contributor than the one who ships fast and explains nothing. The recognition should reflect this.
