18 November 2010

5 Steps to Making Your Boss Read Your Technical Reports

As an IT professional, you probably find it hard to communicate effectively with your less-than-technically-adept manager. Dr. Masha Petrova is determined to help you get your point across, and suggests 5 essential techniques that will get your documentation read.

Fact: people’s attention spans decrease exponentially with respect to their height on the corporate ladder.

Have you ever spent an hour writing an email to your boss about the proper use of the company CMS, only to have him tell you the next day:

Bob, the instructions you sent me are way over my head. How about you just walk me through them every time I need to use the software?

You then have to work to keep your almost-tangible frustration in check, as you explain the same steps every time your boss needs help with the software. Instead of saving yourself time by writing down the instructions for your boss, you’ve ended up losing hours.

Clearly, writing technical instructions, reports, budget proposals, or project summaries for management, marketing, or sales (basically, anyone not as technically knowledgeable as you), requires certain types of skills. Yet these skills have nothing to do with how much technical knowledge you have, but everything to do with how well you can convey that knowledge to someone without your technical background.

In the past, I have met many technical professionals frustrated with the lack of clear guidance on how to get their less-technical managers (or peers) to actually read their documentation. I hope to help to alleviate this problem. Here are 5 Easy Techniques which will ensure that your next report, e-mail or written instructions are as clear as possible.

1) Before you write, answer the following:

  1. Who is your reader?
  2. Why are you writing?
  3. What actions do you want the reader to take?

Every time you sit down to write instructions for a user manual, directions on how to use a certain protocol, or even just a technical project summary, you need to answer these questions and tailor your writing accordingly. For example, if you’re writing a technical summary of a project for the program manager, your answers to these questions might be:

  1. Who: This project summary will be read by a program manager who is in charge of next year’s budget. The manager has a background in accounting and is not closely involved with the technical details of my project.
  2. Why: The manager asked me for a summary of my project, so I naturally want to show him that I did a great job. However, he is also deciding on next year’s budgets, so I want to make sure that he understands why we need extra funding next year.
  3. What actions: I want the manager to allocate more money for my project next year and to give me a raise.

If you keep the responses to those three questions in mind, you are more likely to produce a technical project summary that focuses on highlighting the results and benefits of the project. You are more likely to create a summary that emphasizes how you’re helping the company reach its goals,instead of describing every technique and engineering process you used in the project (which might be very impressive, but simply describing them is very unlikely to encourage your manager to follow up with the desired actions)

Here is another scenario; say you are writing an email with some technical instructions. Your answers to the above three questions might be something like this:  

  1. Who: The Company’s Sales Guy (we met him in The Art of Dealing with People). Enough said.
  2. Why: The Sales Guy keeps interrupting my work and wasting my time by asking for my help with MS Outlook. I’ve decided to create written instructions for him to follow whenever he needs to perform certain tasks within Outlook.
  3. What actions: I want him to stop bugging you every time his Outlook crashes. Instead, I want him to follow my written instructions.

If you keep these responses in mind as you write your email, you are more likely to create instructions that the Sales Guy will understand (as opposed to instructions that a fellow IT pro would understand). As you write, you will remember that the goal of your email is to keep the Sales Guy out of your cubicle rather than proving how much knowledge you have about Outlook. As a result you will try to make the instructions as clear as possible for someone who doesn’t have your extensive background knowledge.

As you write, keep asking yourself the Who, Why, and What Actions questions periodically, and make sure that your writing is always consistent with the answers to those questions.

2) Put the Main Idea of your writing Up Front.

As mentioned earlier, people’s attention spans decrease exponentially with respect to their height on the corporate ladder. So grab management’s attention immediately.

To add to the communication confusion, technical professionals, such as engineers and programmers, tend to be very detail-oriented, while marketing and upper-management are typically more focused on the so-called “big picture”.

Sure, there are always exceptions, but when was the last time you met a good programmer who did not to pay attention to the details? On the other hand, I’ve been told that the best sales professionals do not get bogged down by technical details.

When writing a report or instructions for anyone, catch their attention immediately. This is especially true if your document is going to be read by someone a few steps higher than you on the corporate ladder, or by someone in the sales department.

The way to do this is to put the main idea of your writing right up at the start of your document (notice how I started off “Technique 2” above?). If you want to hold peoples’ attention, you have to explain why they should read what you’ve written, and explain it in the first few sentences of the first paragraph. It should be obvious to management why they are reading your document within the first 20 seconds of looking at the front page. Putting the key points up front will also set the context for the rest of the document, which will make technique #1 easier to stick to.

3) Make your writing ”scan-able”

While we’re on the subject of your readers’ attention, you need to make sure that you can hold their attention once you’ve got it. To that end, my next tip is to make sure that your writing is scan-able. Most people will quickly scan a technical report or email before deciding which parts, if any, are worth reading. Make it easy for your readers.

Keep paragraphs short – 5 to 6 sentences per paragraph (2 to 3 sentences in e-mails).  

Use headings with verbs in them. For example, if writing software instructions, the heading Graphs works ok, but Creating and Editing Graphsworks better. This is working on the same principle as Technique #2, in that it helps your readers to understand the context of what they’re about to read, and to set their expectations about what they’re going to read. That may not sound like much, but it will make a huge difference when it comes to getting your material read.

This step will make a huge difference to the amount of content that your readers will actually look at. It shouldn’t, in an ideal world, but it will.

The following example is from Knowledge and Data Engineering, IEEE Transactions,  Feb 1994  Volume #6, Issue #1:

Non-scan-able
“Recently, attention has been focused on spatial databases, which combine conventional and spatially related data, such as geographic information systems, CAD/CAM, or VLSI. A language has been developed to query such spatial databases. It recognizes the significantly different requirements of spatial data handling and overcomes the inherent problems of the application of conventional database query languages. The spatial query language has been designed as a minimal extension to the interrogative part of SQL and distinguishes from previously designed SQL extensions by: the preservation of SQL concepts; the high-level treatment of spatial objects; and the incorporation of spatial operations and relationships.”

Scan-able!
“Recently, attention has been focused on spatial databases, which combine conventional and spatially related data, include such as geographic information systems, CAD/CAM, or VLSI.

A language has been developed to query such spatial databases. It recognizes the significantly different requirements of spatial data handling and overcomes the inherent problems of the application of conventional database query languages.

The spatial query language has been designed as a minimal extension to the interrogative part of SQL and distinguishes from previously designed SQL extensions by:

  • The preservation of SQL concepts;
  • The high-level treatment of spatial objects;
  • The incorporation of spatial operations and relationships.”

4) Write just right.

If your instructions are too long, too brief, too detailed, or assume too much prior knowledge, your manager will not follow them, or even really try to understand them. If your email is not written in complete sentences or uses too many abbreviations, then you’ll get the same result.

Double-check your work to make sure that you are writing in complete sentences and that you define all acronyms, but, at the same time, do not overload the reader with details that are marginally relevant. Enough detail to get the point across is good, but too much detail will work against you:

Too specific:
“A significantly copious ebony animal of the canine species jumped over the garden palisade.”

Too Abbreviated:
“Lrg K-9 jumped fence.”

Just Right:
“A large black dog jumped over the fence.”

5) When in doubt, cut it out!

If you only remember just one technique from this article, remember this one. Whether you’re writing a simple email with how-to instructions, or a quarterly project report, you naturally should proofread and edit your work. As you read each sentence, ask yourself if it is consistent with your answers to the questions in Technique #1 (i.e. Who is your reader? Why are you writing? and What actions do you want the reader to take?). If not, delete it. Some editing guidelines to keep in mind are:

  • Cut out any sentences or words that sound extra “smart” and which you feel impressed with yourself for having written. Your goal is for your readers to understand you, not to prove how many technical terms you know.
  • Delete any acronyms that are not absolutely necessary to help your reader take the needed actions (on which you decided when deploying Technique #1).
  • Delete anything that sounds confusing or not straightforward. You can always clarify a specific detail later, after your boss actually reads your email or report and actively asks you for more detail.

These editorial steps will help you to avoid having your boss coming into your cubicle and saying:

Bob, I got your email / report / instructions, but it was too long, why don’t you just explain it to me in person?

Final Points

Remember that less is more when it comes to writing for those with a non-technical background, and that clarity is king. Use these 5 techniques when writing and you’ll get your documents read in no time!

This article was commissioned by Red Gate Software, engineers of ingeniously simple tools for optimizing your Exchange email environment. Find out more.

Keep up to date with Simple-Talk

For more articles like this delivered fortnightly, sign up to the Simple-Talk newsletter

This post has been viewed 16295 times – thanks for reading.

  • Rate
    [Total: 36    Average: 4/5]
  • Share

Dr. Masha Petrova

View all articles by Dr. Masha Petrova

Related articles

Also in General

Managing Printers with Group Policy, PowerShell, and Print Management

Just because it is possible to do many configuration jobs 'click by bleeding click', doesn't mean that it is a good idea. It is better to step back, plan, and use the advanced resources provided for managing large network. Printer configuration is the perfect illustration of this, and Joseph demonstrates how the use of Group Policy, PowerShell, and Print Management can turn a time-consuming chore into a pleasure.… Read more

Also in Masha Petrova

4 Geek Excuses for Bad Presentations

Frustrated by technically interesting yet agonizing conferences, Dr. Masha Petrova leaves geeks with no excuses for making bad presentations, and begins her campaign ensure that the people with good ideas also have good presentation skills to back them up, and get them noticed.… Read more

Also in Sysadmin

PowerShell Desired State Configuration: LCM and Push Management Model

PowerShell's Desired State Configuration (DSC) framework depends on the Local Configuration Manager (LCM) which has a central role in a DSC architecture. It runs on all nodes that have PowerShell 4.0 or above installed in order to control the execution of DSC configurations on target nodes. Nicolas Prigent illustrates the role of the LCM in the 'Push' mode of configuring nodes.… Read more

Also in Technical Writing

Writing Outstanding Proposals

Oftentimes you will be forced to learn how to write proposals without a whole lot of help. You can learn, and be taught, the skill of writing an outstanding proposal, but you can't do it without a fair amount of practice. Today, Dwain explains how to write proposals that can be judged to be outstanding and what, specifically, that means.… Read more
  • timothyawiseman@gmail.com

    Excellent Advice
    Writing well and communicating clearly is challenging, and it requires practice and patience. I believe you have provided some excellent advice in that field.

    I think #4 might be rephrased as “Make your writing clear and concise, but not terse.” Or to borrow a quote from Einstein “Make things as simple as possible, but not simpler.”

Join Simple Talk

Join over 200,000 Microsoft professionals, and get full, free access to technical articles, our twice-monthly Simple Talk newsletter, and free SQL tools.

Sign up