One of our favorite anecdotes that illustrates just how hard it is to get people to read the docs comes from an unexpected source: Van Halen.

The rock band was notorious for the whimsical and oddly specific demands about their backstage set-ups at concerts. Spanning a whopping 53 pages, the band’s standard contract included demands ranging from “herring in sour cream” to a “large tube of KY jelly.” But it’s in the “Munchies” section where we find the infamous “M&Ms clause”– WARNING: ABSOLUTELY NO BROWN ONES.

So, a lucky someone at each venue was given the task of plucking the brown M&Ms away from their yellow, green, and orange counterparts. Keep in mind, this was in the 1980s, so there were actually two shades of brown M&Ms at the time, the standard brown and tan, which was eventually eliminated to make way for blue.

If any brown M&Ms were found backstage, the band could cancel the entire concert at the full expense of the promoter.

So what gives? Obnoxious celebrity self-indulgence? Superstitious quirk? Candy racism?

The canary in the coalmine

The truth, as it often is, is much more pragmatic. Anticipating that no one's going to read the contract, the band devised a simple test to ensure that all their technical specifications had been thoroughly read and followed to a T.

“Van Halen was the first to take 850 par lamp lights – huge lights – around the country,” said David Lee Roth, the lead singer of Van Halen. “At the time, it was the biggest production ever.” Without specific guidelines, floors could buckle and collapse, beams could rupture, and the lives of the band, their crew, and fans could be at serious risk.

So, if brown M&Ms were in the backstage candy bowl, Van Halen surmised that more important aspects of a performance – lighting, staging, security, ticketing – may have also been botched by an inattentive promoter.

“I came backstage. I found some brown M&Ms, I went into full Shakespearean “What is this before me!?” ... you know, with the skull in one hand ... and promptly trashed the dressing room. Dumped the buffet, kicked a hole in the door, twelve thousand dollars’ worth of fun.

The staging sank through their floor. They didn’t bother to look at the weight requirements or anything, and this sank through their new flooring and did eighty thousand dollars’ worth of damage to the arena floor. The whole thing had to be replaced. It came out in the press that I discovered brown M&Ms and did eighty-five thousand dollars’ worth of damage to the backstage area.

Well, who am I to get in the way of a good rumor?”

— David Lee Roth, lead singer of Van Halen

The moral of the story? People don't read

Whether it's a contract, an app's terms of service, a design document, or your corporate wiki, docs rarely get a thorough read-through from their target audience. The TAGRI principle of agile documentation –“They Ain’t Gonna Read It” – doesn't just apply to software development but to all kinds of internal documentation.

So, why bother writing?

If no one's going to read your design doc or wiki entry, why waste time writing and maintaining them? All too often, this leads to a vicious circle: writers don't feel it's worth their time to properly document stuff since no one's going to read it anyway, and readers never bother reading the documentation since it's always incomplete or of low quality.

Is documentation a pointless endeavor then?

Without documentation, all knowledge is passed down via an oral tradition. It may work, to a point, when your team is co-located, and small – that is, unless someone gets hit by a bus.

But as soon as things start to scale, problems arise. New people come on board, change projects, move teams, get sick, go on vacation, leave the company. They take their knowledge with them – knowledge sometimes accrued over years of learning the intricacies of your company’s technology stack, internal processes, and know-how. As a result, new employee training takes longer, mistakes are repeated, productivity doesn't ramp up.

Yes, people don't read the docs. But that doesn't mean they shouldn't be written at all – rather, they should be designed for people who don't read.

People don't read – and that's okay

Most people aren't going to read your documentation cover to cover, no matter how perfect it is. Not because they are lazy – they are too busy getting work done. Properly reading the docs can take hours, and most don't have that much time to spare.

And the truth of the matter is, the best documentation is not designed to be read. In fact, trying to write documentation with the expectation of it being read is often what dooms it in the first place.

What people actually do is consult documentation, which usually takes place in the context of another activity. And the fact that they consult it is more than sufficient justification for creating it, and for doing it well.

Writing docs to be consulted

The way your team interacts with your internal docs has a big impact on their productivity:

• Every time they have a question and pause to look something up in your wiki, there is a pause in their productivity.

• The longer they struggle to find answers, the longer the pause.

• If they fail to find what they need, they either give up on the task or have to invent a new way to solve it, resulting in a significant slowdown in their productivity even after they do get back to work.

The goal of documentation is to enable your team to find the information they need when they need it, in as little time as possible. It's meant to aid them in their work and then stay out of their way. That rarely means reading anything cover to cover. So rather than trying to discipline your team or trick them into reading everything, we need to train ourselves to design, write, and organize our docs to be effectively consulted.

Have a single source of information

When you single-source information you strive to record it in one place and one place only. Don't expect people to be willing to waste time hunting through outdated or duplicated Confluence pages, random Google Drive folders, or stale emails. Enable them to look things up quickly and effortlessly – which can only be achieved if all answers are in one place.

Keep your documentation agile

Contrary to popular misconceptions about agile documentation, it's not nonexistent. It's merely handled effectively, which, in practice, indeed proves to be a lot less documentation than what traditionalists write.

Don't document just for the sake of having comprehensive documentation. Write down what you need and only what you need, with a clear purpose and audience in mind. Stick to an agreed-upon content structure and appoint a “wiki gardener” to prune and edit down the docs, keeping the wiki light and manageable.

Design for search, not table of contents

Great content is useless if no one can find it. Most of your readers aren't going to scroll through your table of contents or any other navigation tools you provide – they will use the search function to find what they are looking for.

Whatever internal wiki or documentation tool you choose to organize information, fast and reliable search is the single most important feature you will need. When you have thousands of documents, the last thing you want is to manually scroll through them or wait for a 2-minute search to yield the results. Your content also needs to be designed to be discovered, which means including relevant keyword variations to match the common queries.

The easier you make it for people to find what they need, the more likely they would be to consult the docs regularly.

Write in the form of bite-sized nuggets of information

We are impatient and have a shorter attention span than a goldfish. To be properly absorbed, information needs to be organized in a way that accommodates that.

Avoid long multi-page documents that cover broad topics, keep your docs short and specific. Provide just enough context, and use internal links to guide the readers who want to learn more.

Using the “Brown M&M” test and burying hidden checklists in your docs could help you catch the lazy readers red-handed, but your efforts will have a much better pay-off if the way you write your docs accommodates the human nature of not wanting to read them.