Documentation and Scale
Having good documentation ought to be an uncontroversial goal. Nevertheless, internal (non-customer-facing) documentation is often seen as a non-priority, or even a liability that entails maintenance overhead. Here are a few reasons to prioritize documentation of internal systems:
Improve consistency. Teaching by word of mouth is error prone, because transmission of information from person to person is inherently lossy, as anyone who has played Telephone knows. Even for a single person, it’s easy to misremember procedures, conventions, or anything else without even realizing it.
Help newcomers. It’s inefficient (and mean) to make newcomers learn by chasing down old hands, begging for information. Oh company elders, won’t you sing me the saga of deployment? (I once heard a coworker call such entrenched experts “swamp guides.”) Good documentation defeats the weird, unpleasant power dynamic that comes with information disparity.
Scale. Suppose that, on average, each existing team member must teach each new hire about one topic through direct, one-on-one conversation. (This is common at small companies. You never see it at big companies, specifically because companies that work this way don’t scale.) Growing such a team to N members requires O(N²) conversations.
Instead, suppose each team member writes a document about their topic. Newcomers read the documents. Such documents quickly improve in quality, thanks to the feedback of early readers. One-on-one interactions become a matter of choice, rather than desperate necessity. A quadratic number of expensive, ineffective, error-prone meetings are replaced by a linear number of easily versioned and referenced documents.
You might think you could replace one-on-one conversations with classes, but classes reduce cost by a constant factor (the class size) that isn’t sufficient to defeat the quadratic complexity of “oral tradition” based knowledge transfer. Classes also don’t let newcomers learn at their own pace the way documentation does. Self-paced learning is a powerful force for good in the world.
Even imperfect documentation is better than nothing, but investment in clear, simple, well-written docs is one of the most effective ways to empower a growing company. This is especially true for software engineers, who have a wonderful tendency to turn well-written documentation into automation.