Nine little known secrets about creating great user information
By Ellis Pratt, 18 July 2007
1. Don't worry about the title.
People often get "writer's block" at the start, struggling to come up with the right title for their document. In fact, it's better to write the title at the end of the project. You're more likely to come up with a meaningful description, and do it in less time as well.
2. You can use four of Aristotle's "five principles" to write great documents.
The Greek philosopher Aristotle developed a method for structuring a presentation that is really useful for preparing a document or presentation today. You can use four of Aristotle's "five principles" as a way to plan your work:
- Identification- Make sure you identify the central question or subject.
- Arrangement - Put the structure together to form a coherent argument.
- Language - Use a style of language that's right for your audience.
- Delivery method - Use the right delivery method. This can include the "look and feel", effective use of voice, tone, etc.
3. You can plan and predict what will be in a nearly all documents before you start writing, and save a lot of time in the process.
Outlining and structuring the manual are the most important major steps in creating a manual. Indeed, professional writers spend up to 50% of the total time on this task. It is here that you establish the logical relationship between ideas, and establish the intelligence, value and success of what you write. However, never try to do an outline of the manual in your head. Your brain will work much more efficiently if it receives input from the senses. If you don't believe this, time yourself working out in your head how many permutations of the letters ABCD there are (ABCD, ACBD, etc.)
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.
On a blank piece of paper, write down all your ideas and thoughts about what should be included. These ideas will flow when you ask yourself 'how, why, when, where, what, and who'. The ideas should be jotted down quickly in random order. Don't write your ideas down as sentences; use key words. Once you are confident that you have written down all the major points to be covered, start assembling these ideas into like groups. This will probably prompt some more ideas, and you will eventually arrive at some sort of outline, which can then be polished by turning your key words into completed phrases. At this stage you may start to prepare the structure.
4. Content Management systems can save 30% of your writing time.
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.
5. Documents designed to be read on paper don't work when they're read on a screen.
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.
6. Word may not be the best tool to use.
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.
Unfortunately people rarely write documents in a way that enables them to do this with this type of information. Indeed, the tool you're more likely than not to be using to write documents - Microsoft Word - may not be the best tool to use.
However, there are still some useful things you can do when you're using Word. 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.
Indeed, Microsoft Word has an outline view that lets you see the structure of your document, provided you have used the standard heading 1 to heading 9 styles.
7. Even the best writers have their documents reviewed and proof read.
You can look at a document a hundred times and still miss errors. Getting somebody to review your documents will benefit you by reducing errors and getting feedback on what your readers are likely to think about your information.
8. Different audiences deserve different documents.
If you have more than one type of 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.
9. There are experts in this field who can help you.
There are experts in this field who can help you, who are typically called editors, technical writers, technical authors, information designers or copywriters.
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.