DocumentationDrift.md

The accuracy of documentation is proportional to the time since the documentation was written, and the proximity of that documentation to the code it refers. The name of an variable is more accurate in describing the variables purpose than a comment next to the variable, which is more accurate than a block comment above the routine wrapping the variable, which is more accurate than a readme in the repository housing the routine, which is more accurate than a seperately tracked wiki documenting the repository. However, if the wiki page was written yesterday, it is likely still very accurate.

// lower is better
const accuracy = age * proximity;

The age of documentation should be taken as the time between publication and the last code update. For this reason, git commit messages can be thought of as perfectly accurate. Git requires a commit message to be provided right as the code is committed, so the age of the commit message for a particular line of code is always zero. You can use version control to correlate the age of documentation to the last time code was updated, and take this as the age of the documentation, but that is more effort. In the absence of this knowledge, the actual age of the documentation can be used, which assumes the code has been under active development since the documentation was written.

The accuracy of documentation will drift less if it is kept closer to the code because developers will be more likely to update it as needed for changes. Many tools exist to push documentation closer to the code in order to exploit this phenomenon.

#software