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!)

Like many technically oriented folks I have a love/hate relation with documentation (shortened to “docs” occasionally). In many ways it’s the fastest & least obtrusive way to gain knowledge about something. It can open up new & interesting options that can revolutionize your entire interaction with that item (Love ? — try to step through changes piece by piece). Reading the docs can be a treasure hunt for greater heights of esoterica — that will confound co-workers & impress supervisors.

On the other hand, there are times when reading the documentation on a project is agony. It starts with being overly detailed, or full of developer jargon. Then finishes off any semblance of understanding by using circular references that can confound & infuriate even seasoned tech professionals.

Case in point — here’s a section of the man page for an extremely important utility used by literally half the internet Every. Single. Day.

Synonym for what now?

Now this particular piece of software is complicated, invoking this in my job involves one of the more complicated shell commands I’ve had to create freehand & off the top of my head. Usually it involves at least 3 trips to the docs & at least 1 trip to Stack Overflow & back. In the end, I’ve spent 4 minutes researching a 2 minute run command, which ends up saving me 10 minutes in the end. Can anything be done to clean up the docs above? Perhaps. Has the world burned down because software can be confusing to use? Not yet.

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.

I have a different theory — one that doesn’t involve programmers being incapable of written expression, or rapid obsolescence of technology — an economic theory. Projects live & die on the budget — the central motivation in our capitalist society. Whether that budget is monetary or time-based, it has a laser-like focus of maximizing functionality delivery per given unit. This is not by mistake, nor would I deem it incorrect. Functionality is king.

Software that doesn’t do what it says on the tin isn’t worth its bits on disk. Creating documentation is sacrificed on the alter of functionality more often than any reason of which I can think. Whether it’s scope creep, integration woes, or tasks overblowing their estimates, the result is the same — shipping working code overrides documenting that same code. The end result is functional code that can become an abstraction to the team using it & subject to the ravages of technical debt.

No self-respecting programmer wants to create a one-off, nor should their legacy project become an orphaned island of code. To alleviate the potential for projects to become undocumented backwaters, I’ve created a list of a few potential methods to encourage & highlight creating documentation. As always, YMMV. It never hurts to try.

Suggested approaches to augment documentation

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

This would likely capture as much functional knowledge about the feature. A first-pass draft of documentation would be all that’s necessary. Even something autogenerated from function annotation like Doxygen could be utilized as a stepping stone to more comprehensive documentation at a later date. All told, if writing the documentation for a feature became part of the acceptance criteria, it would be written as part of the delivery.

2. Documentation sprint(s) — time off to write the docs & edit them

How awesome would it be if for the length of a sprint (1 week, 2 weeks, whatever) the only thing to deliver would be a clear, clean set of documentation? What if for two weeks, the only deliverable was getting as much knowledge transferred out of the heads of the developers backed up into written word, accessible by the client & anyone involved with the project? Imagine how much effort would be saved if that project needed more work, & a new team needed to get up to speed quickly! That time savings alone, amortized over a few months, would absolutely pay for the documentation sprint.

3. Final review — give to non-technical, but still familiar with project

Making the documentation accessible to anyone involved in a project is ideal. As such, involving non-programming staff in the documentation creation process is a way to ensure that any conceptual gaps are bridged and that the artifact can be delivered with little introduction to client stakeholders. This is an opportunity to really dress up the documentation, get it reviewed by Project Managers.

Take screenshots — annotate them. I can’t remember how many times a well placed screenshot has made a particular concept click. If the concept seems convoluted, perhaps its time for a diagram? Creating understanding via imagery is a a completely valid method of teaching. Using animation, such as a gif, illustrates a simple concept, repetition is built-in and they draw the reader in.

See how eye-catching that is?

Creating a gif from a screen capture is as easy as 1,2,3. If installing homebrew packages & using the command line is out of reach, there are all-in-one screen capture programs like LICEcap.

In conclusion, the most important step to getting documentation going is to buckle down, focus, and get it done. The mere fact that it exists will put your project head and shoulders above the rest, simply by being more accessible.

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