Introduction

Documentation has been a source of frustration and conflict in software development for many years.  The problem is, fundamentally, that many developers don’t document their code, or do so poorly.  As a result, other developers who need to understand the code they are utilizing or changing spend many frustrating hours addressing this shortcoming. Understanding code can take as much as 10X the amount of time as writing new code.

Why don’t developers document their code?

There are many examples of articles and posts that discuss this question.  For instance, this article in Infoworld from 2012 asks “Why don't programmers document?  Real programmers don't document is an old chestnut of hacker machismo, one that some coders have sadly taken to heart,” Infoworld states. Their answer might reflect a nugget of truth, but is by no means a universal explanation nor a solution. In a post in 2018 Tomer Ben Rachel argues that “The main reason code goes undocumented is because of time. When developing a feature that needs to be completed within a certain time frame, rarely do we have a moment to stop everything and focus on documenting our code.”

In an all-remote world, documentation is one more essential tool to sustain team alignment. This is a great moment to revisit how we think of documentation and its value.  The good news is that there is a better way.

Continued here.