Good Documentation

Good Documentation is life-changing.

The effects of missing documentation are brutal - this is a type of “business debt” that accrues silently and makes margin calls at the worst time.

I started thinking about why scaling teams often suck at this.

No one’s job

Number 1 reason is perhaps because it’s often no one’s explicit job. Non-functional requirements like “document your decision making” are rarely measured or managed.

No time to plan for success

But that is maybe a cop-out. I’ve also found that sometimes it seems to make sense in the moment to skip documentation.

“Writing this is usefless, this is v1, it will change in a few weeks”

In product briefs, good PMs often plan and mitigate for failure. BUT I think it’s fairly uncommon to plan for success. And runaway success? documentation isn’t something you normally think to loop back to.

Why this sucks: It’s often the mark of an experienced programmers to refuse to refactor areas they don’t understand (especially if they don’t trust their test suite.) So one effect of documentation debt means it gets harder and harder to change legacy decisions. This intertia ultimately leads to shitty outcomes which is accelerated by the speed of scaling out the organization.

No one else will care

“But only our team cares about this and we all understand it.”

Scaling companies are often adding dozens of new people monthly. Your team will grow, it will add people, and they will spend at least 10x longer trying to understand past decisions and code than time was spent on actually deciding or writing it. Think of documentation as an investment into the 1/3 of your team that will be hired in the next year.

This issue then compounds itself as tribalism starts winning - the only way to understand the system is to talk to people who have been there the longest. This then turns into a disruption-culture where your most experienced folks are getting 20 slack pings a day!