Don’t Bury Important Information in Trivia
We have all seen these: thick specifications that, despite their great level of detail, don’t actually communicate much about the project.
Nobody really wants to read that sort of thing anyway. Those who are required to do so often complain about the information being hard to find and follow, even being contradictory in places. “It’s frustrating,” a colleague of mine once said. “It looks like the real thing, but when you dig deeper, a lot of important information is missing. While at the same time, there is a huge amount of superfluous information and copy-paste that doesn’t serve any real purpose.”
Thick documents are great for obfuscation. But what if you actually want people to read and understand what you have to say?
In the 1990s, I was an intern in a major multinational corporation, and that’s exactly how we did things then. It was all about the number of pages a team was able to produce to confuse the other side, so to speak, just in case.
But what if you actually want people to read and understand what you have to say?
Logically, you should strive for the exact opposite: compiling all the important information in an easily digestible package. Unfortunately, we are often slaves to our habits, and many people simply don’t think about the commonsense approach to a given task. They write their spec in exactly the same way as if they were intentionally trying to confuse their audience.
Communicating Well Is Your Responsibility
A weather forecast is presented in terms that everyone can understand: what the temperature is expected to be and whether it will be raining. All of the information that viewers want is delivered in less than two minutes. How would you feel if the weather forecast lasted for an hour and still left you digging for the essential information that you actually need?
The responsibility to deliver the message lies on the communicator, not the audience. Therefore, arguments such as “It’s all written in there, you just have to read the document” simply don’t stand. When that sort of answer is given to a genuine question, the response will often be interpreted as arrogant or downright malicious.
The responsibility to deliver the message lies on the communicator, not the audience.
Let’s visualize for a moment what a stereotypical “bad” document looks like:
- It has hundreds of pages.
- It’s hard to find the information that you need.
- Everything is “flat”; it doesn’t communicate the key points very well.
- It contains contradictory information in some places.
- There is clearly a lot of copying and pasting.
- It’s written from the author’s very specific point of view, often in highly specialized language.
- It provides a great level of detail on some topics, while others are left ambiguous.
There are more, but you understand the point. Avoiding the above issues is the easiest way to improve how effectively your specification actually communicates what you have to say.
Avoid Creating Thick Documents
Most movies last just above one hour. That’s the norm, because most adults are unable to maintain their focus much longer than that. In fact, it can be difficult enough to gain their attention in the first place.
In terms of the length of your specification, your audience should be able to go through it in a single sitting. If they invest an hour and still don’t understand what you wanted to say, then they are unlikely to voluntarily invest more of their time trying to find out.
A good document is concrete and to the point, and can be read in a single sitting.
If you can say something in two paragraphs, then don’t write it down as two pages of text. If you can do it in two sentences, that’s even better. If you have more information that some people might need, put it in the appendix and point interested readers in that direction when necessary.
The same “main document plus appendices” strategy applies for situations where your work is evaluated based on the number of pages you produce. If one of your tasks is to generate 500 pages, that doesn’t mean you have to make life harder on the people that will eventually be reading your document.
The quick rule-of-thumb is that you need to present all the important information in approximately 30 pages. This recommendation doesn’t fluctuate based on the size of your project; it is designed based on the capacity of your audience to receive and digest the information.
Focus on What Is Important
If your main document is written in an “introductory” style, then some people will feel that it is wasting their time. Thus, you should be straight to the point and write what the project is all about, what exactly it will accomplish, and how.
Since the “how” is presumably what such a document is all about, you will have quite a lot to say on that particular point. The real problems occur when you begin writing down everything that you know on the topic. Aside from creating a long document, it’s counterproductive for other reasons, which include:
- Audience would have to discern for themselves what’s actually important.
- Gaps in the information would be easy to miss.
To avoid this, start with what’s important and don’t go any deeper until the whole picture makes sense, at that “broad strokes” level. This also allows you to identify and solve any remaining questions that you may have.
Start with what’s important and don’t go any deeper until the whole picture makes sense.
When you do get to the details, remember that there are three kinds of those:
- Details that are important.
- Those that you need to write down to avoid confusion or ambiguity.
- Things you feel you should include for the sake of completeness.
My advice is to completely skip those details that contribute solely to completeness. They don’t add any value; they simply make your document thicker. Also, to readers’ eyes, those details look the same as the important ones, so they are further contributing to confusion. If you feel that you must include these details, put them in the appendices.
For the first two types, be sure to make it clear what’s important in and of itself and what just needs to be there. You should either separate the important points from the overall structure, or at least e.g. make the font bold; be sure to accentuate them in some way.
In short, don’t mix important information with details, and don’t focus on the form over the context. Unless, of course, you are intentionally trying to hide something.
Are Templates Good or Bad?
Basing your work on templates often results in it containing a lot of extraneous information. That’s what templates do: they ensure that you haven’t omitted anything important. To achieve this, they require the person using the template to fill in all of the information required in the predefined structure.
The advantage is that a template can be developed once by someone with extensive experience and then used by countless others afterwards. This is very useful when part of the work is conducted by less- experienced colleagues.
However, the template author can’t anticipate what will be important for each particular project. Thus, a good template throws a wide net to catch what you are after, but that also means pulling in a lot of extraneous stuff onto the metaphorical boat. Therefore, after you get the results, you should do the same as fishermen do all the time: sort it all out and throw out everything that doesn’t have value.
If you make it easy for your audience to understand what you wanted to say, then they will accept your specification and rely on it.
Unfortunately, this step is often skipped for various reasons, the most frequent reason being the ease of evaluating whether all the work has been done. A boss can easily check whether all the information that a template requires has been filled in. When several companies work together, then even a copy-pasted paragraph is an explicit statement of taking responsibility for the content.
However, the kind of output that this approach produces does not effectively communicate information. You need to make sure that your process doesn’t skip the task of sorting out what adds value to your document and what doesn’t..
One strategy that works is to have “guidelines” rather than templates. They give a broad outline of the resulting document, along with instructions and the checklist. The instructions provide the knowhow, while the checklist makes sure that the work can be easily evaluated.
However, if you are stuck with templates, you can always go back to basics. Develop a good “master document” as described earlier and provide the detailed template-based documents as attachments. The master document is intended for consumption, while the attachments serve as a reference, when necessary.
Your Goal Is a Specification That People Want to Read
I have been lead analyst on a project that was based on a thousand-page tender. It was funny in some bizarre way that these thousand pages told us practically nothing about the results that we were expected to provide.
If your goal is to communicate information, then you can’t allow such a huge effort to go to waste.
1. Keep your main document short, right around thirty pages. Documents of this size can be digested in a single sitting, and you can walk your audience through the complete document yourself, if necessary.
2. Be concrete and to the point; don’t use two pages where two paragraphs would be sufficient. You need to win your audience’s attention, while simultaneously showing them that you are not wasting their precious time.
3. Don’t mix important points with the details and use appendices liberally. If part of your work is based on templates, ensure that the information is sorted out based on its value before it’s presented.
In short, if you make it easy for your audience to understand what you wanted to say, then they will accept your specification and rely on it.
- Check the infographics I’ve made on good vs bad specifications.
- Leave a comment, I’ll be glad to know what you think.
- You can share this article with others. To do that, just use the social buttons below.