Imagine this situation: Sandra is back at work from an overseas holiday of three weeks. She meets the department manager in the corridor. “Morning Sandra.” he says. “You’re back. How was your holiday? Did you go away?” Sandra tells him she had a great holiday and went to Italy with her family. “Sounds amazing!” he replies, and continues to his meeting. When she joins her team, her colleague Ella asks about her holiday too. Ella knows Sandra went to Italy and is planning a holiday herself. She asks lots of questions about the hotel, the travel and the food and they have a great chat. Later that day, Sandra has lunch with Tom who is a friend as well as a colleague. He knows Sandra also met up with her sister on the holiday, taking a break from a really bad year with an ugly divorce. So they chat about this emotional part of Sandra’s holiday.

Now what does this little history have to do with writing user-oriented documents? Actually, we can look at Sandra as an extensive document aimed at different audiences. Each user of the document is a different conversation partner. They want to find out what is relevant for them, and be able to skip any unnecessary parts. Sandra’s manager is looking for the main high level points, Ella looks for specific information about Italy and Tom is looking for the personal edge – but they all get this info from one source: Sandra.

The business proposal

Let’s move this to a business documentation space. I recently redesigned a proposal to introduce a new incident reporting system in a business. While the original document contained all possible information about the proposal, it was quite hard to distinguish all the points that might interest different users. Here are a few examples of what people might be looking for:

• The CFO – decision maker – will want to find out a few things quickly: is the proposed software going to solve a problem and what’s the budget?
• The HR manager is interested in the reporting capabilities of the proposed system, any gaps and how easy it will be to train her team.
• The IT team wants to know the implementation timeline, how easy it is to integrate the new software with other existing systems and any expectations about data migration.

Principles to write user-oriented documentation

So how can you approach a document and make it good to use for all? By making it easy for each user to find the information they need and not burden them with stuff they are not immediately interested in. The principles of the Information Mapping methodology can guide you along. Let’s unpack that.

Chunking and labeling

Make sure you stick to one idea per block of text, and provide a clear title. This allows your audience to find the information they need quickly, and they can skip anything they don’t need.

Example: If the CFO wants to find the pricing and compare it to their budget, clearly label this piece of information. Don’t add other content in that same text block, like why this software is the best choice for what the business needs. If the CFO wants to find that out to further inform their decision, again, they should be able to find this detail easily because you have labeled it clearly as well – but with a separate block of text.

To stay with the analogy, if Sandra’s colleague Ella asks about the hotel they were staying at, but she has no kids, the offer of a kids club and a great playground is not something she wants Sandra to elaborate on. Information about the rooms, the location, etc. is the relevant detail that Ella wants to access. Another colleague might be interested in this parts and will ask Sandra that question: “Was there a nice playground?”. Great labeling and separating content in chunks is again, the best approach for a user-oriented document.

In short, a user needs to be able to find a concise yet complete answer to their question without having to read through a whole bunch of text. They scan for a label, and under that label they find exactly the information they were looking for.

Relevance

Next, the relevance principle helps you to put “like with like” and to create an information hierarchy. For example, in a first block of text you may provide a list of the main functionalities of the proposed incident reporting system. Then, close to this overview, but in separate, clearly labeled blocks, you can elaborate on each feature so users can look for more information on each feature they are interested in, but skip the ones that are not relevant for their department.

It’s about answering questions

In summary, working towards chunking can be guided by imagining questions from the user. What would they want to ask you? And how do you answer each question in a succinct way in the document? Relevance can be guided by thinking of follow-up questions: when the conversation partner has received a clear answer, which further detail might they be interested in? As a closing analogy – Ella could ask Sandra if their hotel was all-in, and the answer was yes, breakfasts, lunches and dinners were all buffets, included in the price. High level question, answered clearly. Ella’s follow-up question could be: did they cater for gluten-free and vegan? She would then be able to find that answer close to the “food” block as it is relevant, but under a clear label “catering for dietary requirements”.

So next time you write a business document think about your readers as conversation partners: what would their questions be? How detailed would they want to go on follow up questions? Do I give them all the answers and how easy for is it for them to find them?