Uncharted Waters

Nov 30 2019   8:27PM GMT

Documentation as Waste

Matt Heusser Matt Heusser Profile: Matt Heusser


A few days ago, I put out a post on twitter about Documentation.

documentation as waste

That post was my most-replied-to, most-liked, most popular in weeks.

It’s time we talked about it.

The Response

The majority of people agreed with my claim. As you can see, Dave Nicolette thought my number was low. I went on to propose that there are perhaps a few different skills. First, knowing what needed to be documented — separating the wheat from the chaff, so to speak. Second, there is the ability to write in an entertaining way, so that people actually will read the documents. Third, there is the ability to make your key information discoverable.

Without those skills, any given person in IT is likely to produce a bunch of … stuff. Some of it is relevant, some of it is not, finding what you want is hard. All of it is boring.

I remember one colleague had to say, dozens of times “The answer is in the email.”

The email was so bad that people could not force themselves to read it, to find the needle in the proverbial haystack.

Another time, I needed two pieces of information to make a one-line code change – the value to search for and the value to replace it with, which were the essence of the code change. I sent email back and forth to the analyst, a half-dozen times, asking for the information. She said it was in the four page requirements document. Of course, it was not. Most of the document was cut and pasted template information, the project number, date, requestor, PM charge code, project, program. There was the background, current state, desired state, high level business need, goal … everything but what I had to actually do to make the change.

This isn’t an argument to eliminate documentation, but an argument that if you develop these skills, you won’t go hungry.

Bad Documentation

A few people who read my message thought that it was dangerous, because developers would simply abandon documentation, perhaps heralding the beginning of a #NoDocs hashtag. There could be #NoDocs conference presentations, #NoDocs Conferences, #NoDocs training!

Except that’s silly. It’s embarrassing for me to even mention, as it gives credibility to the not-credible. However, it might be a fun thing to try as an April 1st blog post or webinar.

Lady Gaga’s song, “Bad Romance” describes a bad romance. She isn’t saying to give up on romance.

She is saying to do better.

Wikis and Mind Maps

MindMap - DocumentationThe image at right is from a real customer. It is a mindmap that describes all the major pieces of functionality. Each end-node contains to a link to a wiki page. In this case, the mind-map was built in MindMeister, and the wiki is confluence. The wiki page covers what the functionality does, how to test it, and general advice for the tester. When testers do a regression shake-down, they make a copy of the mind map, then mark the nodes as taken, then red/yellow/green, and give a rough percentage of coverage.

This entirely replaced an eighty-page test plan document, which got out of date every release. Updating the wiki when the feature changed was simply a task for each story – so things didn’t run out of date.

Of course, that’s human testing. Feel free to hold your nose and refer to me as old-school. The base idea, however, applies to all forms of IT documentation.

At a more recent project we used Gliffy, a diagramming tool for Confluence, to create a site map of all features and what teams owned those features. Along the way we found some “abandoned features” and aligned the project, which was about twenty teams on three continents.


Of course, there are good reasons to write things down. For today, I’ll steer clear of regulated projects, which have their own foibles. Still my friends had a couple of ideas.

Gregory Paciga wrote “The act of writing something down can clarify ideas and force deeper comprehension for the author even if nobody reads it.” Then Gerd Bleher added “[A] Heuristic that helps me: if I had to explain something two or three times, I’ll write it down. Most likely there will be more ppl wanting to know. I know what they want to know. And having explained it helps me bringing order into my thinking and expressing it clearly.”

That gives me two ideas: First, write it down after it has been requested a few times. Second, for periodic reports, consider not writing them, and see who complains. If they do complain, try to figure out if you can change the process to generate a visualization for you, as Kanban and Scrum boards can.

I’ve made a career of writing.

… and of knowing when I didn’t have to.





 Comment on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: