Monday, September 26, 2005
Streamlining documentation
When you take over a documentation project, you sometimes find that the book or books you now have responsibility for contain a few too many words. OK, probably more than a few. In fact, they don't need to be that wordy.
I discovered this in my last three tech writing gigs. But by applying a streamlining strategy to the manuals I was working on, I was able to reduce their sizes by between 20% and 65%. And I did it without affecting the integrity or accuracy of the information, or reducing the usability of the guides.
Here is some advice for streamlining your documentation:
Tighten up -- More words isn't always better. If you can convey in four words instead of seven, do so. Cut out any superfluous paragraphs. Find ways to shorten lengthy procedures.
Break things up -- Long paragraphs are easy to write, but they aren't fun to read. If a paragraph is longer than eight or ten lines, try to break it up into two or more shorter paragraphs. Where possible, convert portions of a paragraph into bullets. Adding bullets may not make your document shorter, but it will make it easier to read.
Get rid of screen captures -- Screenshots are useful, but often they’re more eye candy than anything else. Rip out any unnecessary screen captures.
Zap the “That is” -- Far too often, you'll have a sentence that explains something. Then, the following sentence starts with “That is, ...” and reiterates what was in the previous sentence. In that case, the writer was obviously not doing his or her job properly. Try merging the two sentences, or getting rid of one of them.
If the sentence elaborates on the previous one, then just remove the "That is". It serves no purpose.
Put repetitive information in an overview section or chapter -- When documenting software, you’ll find that some procedures, or portions of procedures, are repeated across several features. For example, setting dates and times. Instead of repeating this information in each procedure, put it in separate overview section or chapter. Then, insert a cross reference to the information in the overview.
I discovered this in my last three tech writing gigs. But by applying a streamlining strategy to the manuals I was working on, I was able to reduce their sizes by between 20% and 65%. And I did it without affecting the integrity or accuracy of the information, or reducing the usability of the guides.
Here is some advice for streamlining your documentation:
Tighten up -- More words isn't always better. If you can convey in four words instead of seven, do so. Cut out any superfluous paragraphs. Find ways to shorten lengthy procedures.
Break things up -- Long paragraphs are easy to write, but they aren't fun to read. If a paragraph is longer than eight or ten lines, try to break it up into two or more shorter paragraphs. Where possible, convert portions of a paragraph into bullets. Adding bullets may not make your document shorter, but it will make it easier to read.
Get rid of screen captures -- Screenshots are useful, but often they’re more eye candy than anything else. Rip out any unnecessary screen captures.
Zap the “That is” -- Far too often, you'll have a sentence that explains something. Then, the following sentence starts with “That is, ...” and reiterates what was in the previous sentence. In that case, the writer was obviously not doing his or her job properly. Try merging the two sentences, or getting rid of one of them.
If the sentence elaborates on the previous one, then just remove the "That is". It serves no purpose.
Put repetitive information in an overview section or chapter -- When documenting software, you’ll find that some procedures, or portions of procedures, are repeated across several features. For example, setting dates and times. Instead of repeating this information in each procedure, put it in separate overview section or chapter. Then, insert a cross reference to the information in the overview.
