Why documentation matters

Flicker Evan Goldenberghttps://www.flickr.com/photos/naveg/5047098121

RTFM is a common NSFW refrain in many tech communities

RTFM won’t be defined here, however Urban Dictionary has an excellent entry on it. It usually comes as a response to a question better answered by a quick Google search. If you’ve never been told this, either you’ve never asked a stupid question (unlikely, but possible) or you’ve found an extremely tolerant & welcoming community (great job!)

Synonym for what now?

Writing docs is crucial & not just for obvious reasons

Documentation is a mnemonic device — not in the traditional sense of needing a catchy acronym (Please Excuse My Dear Aunt Sally anyone?). In the sense that in creating the artifact, memory is augmented. Furthermore, writing documentation is helpful in a myriad of unexpected ways such as helping Subject Matter Experts to re-trace the learning process to yield more efficient solutions to create the successful outcome.

Writing docs as a form of mental re-training

Education theory contains a concept called retroactive learning. In a nutshell, retroactive learning is where someone using episodic memory to create understanding that was not originally there in the original trip through the experience. Creating docs provides users with the opportunity to step through the creation process of the solution, which now being in the past, can yield new understanding for the producer. Codifying these breakthroughs in the documentation will allow others to continue the process of improvement & discovery.

Comments in source code != documentation

Many programmers think that writing a few lines of comments in the source code should more than suffice to explain what is going on for a particular piece of functionality. This couldn’t be further from the truth. While commenting code is important, it can *never, ever* replace adequate, well laid out documentation. Not everyone is good at spidering through directories, looking for a README that tersely explains what this component does, or how this controller is invoked, much less opening the source code to look at the function annotation above a method of interest to verify whether or not it can accept multiple arguments or it’ll blow up & take the rest of the application along for the ride. This is a perfect way to ruin a heretofore well-running project. An uninformed user-base can be just as poisonous and destructive as a malicious one. Furthermore, good documentation is a sign of good quality code. Code that can be clearly explained how it works, as well as why, is a hallmark of having truly passionate people on the project.

Why is documentation so hard?

That’s something that I struggle with mightily. Perhaps its that human language is imperfect at translating complicated and often recursive concepts into something that makes sense to others. Perhaps its that a single-minded focus on pedagogy is foreign to the fast-moving world of computer science — when the tools used to build a project are obsolete within a year of their launch, it doesn’t create much space to generate course level content, maybe only a blog post or two.

Suggested approaches to augment documentation

1. Documentation as a final step in completing a feature?

See how eye-catching that is?

nielsonm on D.O. Father. Rabid proponent of ALL things open source. Lover of ethnic food and XKCD.