The adoption of agile software development methodologies has been a necessary evolution to support the explosive demand for new and expanded capabilities. There is no doubt that without the broad adoption of agile practices much of the growth in technology, and all of those aspects of everyday life that is driven by technology, simply would not have happened.

Still, too much of a good thing applies. Another old adage that comes to mind is “You can have it better, cheaper, faster. Pick any two.” Many organizations have insisted on all three. How did they do it? They sacrificed the documentation.

I’m not talking about saving shipping costs and trees by making manuals virtual, and then saving bandwidth by replacing the documents download with the install files with links to online documentation (which has its own issues in this world of massive M&A). I’m talking about all those wonderful references that development teams, sometimes backed by technical writers, produced so that others may pick up where they left off to maintain and enhance the final applications. Yes, that documentation.

Self-documenting code does not make a self-documenting solution

While the no one can honestly disagree with the value put forth in the : “Working software over comprehensive documentation,” I also don’t think the intention was that documentation impedes working software. Still, the manifesto has fed the meme (the original definition, not the funny GIFs) “good code is self-documenting.” When I hear this, my response is “True—and knowing what code to read for a given issue or enhancement requires documentation.” My response lacks the desired impact for two reasons: It doesn’t easily fit on a bumper sticker and it requires putting time and effort into a task that many people do not like to do.