Six biggest mistakes Project Managers make with documentation and how to avoid them

By Ellis Pratt, 16 July 2007

1. They don't communicate their central message and their desired outcome.

It is important you know the key purpose of your document: Who is your audience? What do you want to happen as a result of someone reading it? Try to understand the user and see through their eyes. You can do this by pre-empting questions the readers may have:

• What do you want to tell me?
• Why should I read this?
• What do I need to know?
• What do you want me to do?
• Are you requesting, proposing or seeking approval?

2. They are inconsistent or unclear in what they want to say.

The pyramid style of writing, devised by Ron Blicq, is a very useful way of arranging the structure of your document:

• Start the document by writing "I want to tell you that...", finishing that sentence and then deleting the phrase "I want to tell you that..." This should help you communicate your key message in your first sentence.
• Start every section with a summary overview statement. This will encourage people to read on.
• Follow the summary statement with any supporting details that justify it.

Professional business writers, such as technical authors, typically break a document down into small, discrete units of information, organised around a skeleton of topic headings. If you use this "component" or "modular" approach, you can plan and structure the document using the heading "labels" that describe each section. These signposts help enormously when you start writing, and they can also help you be consistent and avoid missing out any important content. Indeed:

• If you have more than one audience reading the document, don't be afraid to break information into separate documents. You could also provide a series of ways to navigate around the document (such as alternative tables of content, indexes and tags), suited to each particular audience.
• As you write, keep refining your structure, by asking "is this section really relevant?","Is any important information missing?", "Is there a logical flow to the document?"

Your list of headings can be structured to form a storyboard, to guide the reader through your document. Meaningful titles for sections also help with the readability of your document, as they enable readers to scan down a document and find the sections that relate or are of interest to them.

3. They don't use the best style of language.

Here is some advice regarding the words you use:

• Keep your vocabulary simple. This will aid your reader's understanding. For example, "use" is better than "utilise".
• Use the words and phrases your readers would normally use, where possible.
• Be consistent with the terminology you use.
• Check your document for any spelling mistakes.
• Use the active voice, as it will help make your writing seem much more definite and confident.
• Be succinct.
• Separate task (how) information from background (why) and support (what) information.
• When writing instructions: identify who should do what, what you should do before you start and what should happen next.

4. They leave insufficient time to write the information, or spend too much time on presentation.

The best way to get a writing project completed on time is to adopt standard project management principles:

• Set a project plan, defining the purpose, key milestones and deadlines.
• Allocate the resource needed to complete each stage in the project.
• Write a series drafts and get them reviewed.

It's not uncommon for 30% of a writer's time to be spent working on the "look and feel", once all the writing has been done. Of course, documents designed to be read on paper don't work when they are read on a screen, so it's important to change the formatting to suit the delivery medium. The more documents (and the content contained within them) are published in different places, the more important it will be for you to be able to create these without being faced with spending lots of time on reworking. Look at the tools you use, to see if you can control the "look and feel" independently of your content. You can achieve this partly by using standard templates, but you might want to consider using content management software.

5. They present the information badly.

• Don't overload people with information. In other words, don't give them too much all at once.
• Have a presentation format appropriate to the medium readers are using. What works well on paper doesn't always work well on screen.
• Make your information approachable by:
  • inserting plenty of white space between paragraphs,
  • using headings to separate different parts of the document,
  • using only one or two fonts throughout the document,
  • using a easy to read font.

6. They don't have a manageable way to maintain the information.

A key aspect to managing any business information is for people to be able to:

• Maintain, update and improve it efficiently after it's been created.
• Re-use it in other situations, to create value elsewhere (and add value to it).
• Set standard processes and guide staff on what to do.
• Have staff work on it simultaneously and collaboratively.

This is also true for business documents. However, it isn't always easy, with many organisations being in state of having lots of out-of date or missing documents, or more than one version of the same piece of information.

Having a dedicated writing or editing resource, such as that offered by Cherryleaf can help, but it's also important to look at the systems and tools you have in place for creating, maintaining and improving documents.

If you are using a word processor, you can format the headings with the preformatted styles contained in the word processor templates (For example "Heading 1" and "Heading 2" styles in Microsoft Word). A style within Microsoft Word is a set of formatting characteristics that you can apply to text in your document to quickly change its appearance. When you apply a style, you apply a whole group of formats in one simple task. Using styles makes it easier to make changes to the look and feel across the whole of the document, and makes it easier to import the content into other software at any stage in the future.

One popular approach is to have one source for content, allowing you to reuse pieces (or components) of information. These pieces are managed and maintained in a database, and then published to different audiences, documents, and in a range of media formats, such as print and online. You can write information once and re-use it many times, and make changes to it in one place. It promises a reduction in errors and duplication, time needed to review content, translation costs (as you can re-use content translated in the past), as well as better consistency.

For more tips and advice

For free documentation advice, please visit our Web site, and read the articles. Subscribe to our free Newsletter and we can keep you up to date with documentation issues.

Sign up to the FREE 1 Minute Documentation Audit from Cherryleaf to stay ahead of the competition.

This one minute documentation audit can help you identify in seconds, the real reasons why your user documentation isn't generating the results you want.