The Annual Distribution of Meaningless Awards to Shallow People, a.k.a., The Oscars, is fast approaching. This non-event is as useless as a Windows 1.0 user guide. The choices are completely subjective. Many great films and performances have lost out to lesser ones. One of the best examples of this is the masterpiece Citizen Kane, considered by many the greatest film ever made, which lost to – wait for it – How Green Was My Valley.
Now, many STC chapters have awards for technical communication. Unlike the Oscars, this is a useful awards event, if for no other reason than to have one’s work judged by others. Perhaps, though, to liven things up, we need to develop sexier categories:
- Best Looking Cover Page
- Best Performance by an Index in a Leading Role
- Most Graphic Use of a Graphic
- Most Outstanding TOC
- Most Consistent Use of A Comma Before the Word “And”
- Best Use of Bold and Italic Simultaneously
Of course, we’d have to develop a nickname for the trophy. How about the “Writey”?
Doubling Your Pleasure
This year, the Academy has doubled the number of nominees for best picture from five to ten. The official reason is to give less successful but presumably worthy films a chance. The unofficial reason is to boost ticket sales and film rental revenue.
This idea is as dumb as a bag of Oscars. Why stop at ten nominations? Why not have twenty? Or a hundred? Just as printing money lowers its value (something the U.S. is painfully learning), increasing the number of nominated films simply lowers the value of a nomination.
Things that are important are important because there are so few of them. The important things in documentation include:
- the important information users need to know, as highlighted in notes and warnings
- headings, including chapter and other major headings: headings 1 through 3, for example
Therefore, if you have too many of these elements in a document, you weaken the document. For example, if you have six Important notes on a page, the reader may likely ignore them all, since if everything is important, nothing is important. Better to group all these notes as bullets under one Important Considerations section.
As for headings – again, these need to be used carefully and sparingly. Too many chapter and heading divisions in a document dilute the document. You end up with a TOC containing 47 chapters, and a chapter with 37 heading 1 sections. Instead, group numerous separate smaller sections into one large section. Split a super-sized chapter into two or more chapters. Don’t force your readers to wade through a sea of sections. Combine, converge, and conquer.
By doing these things, you’ll create documentation that people can actually use. This is so much more valuable than a 13.5″ statue of a bald naked guy.
I like your new STC document award categories. I've seen many mediocre documents with a cool cover or one killer graphic. The traditional categories and guidelines aimed at overall excellence don't give them a chance.
I had an instructor in college who emphasized that people don't read manuals cover to cover. They may read the initial tutorial section that tells them how to get started, but then they use the manual as a reference.
Our job is to organize the reference information in a sensible order, and to provide as many kinds of handles as possible to help users find what they need when they need it and come back to the manual to look for it. Those handles include headings and subheads, call-outs, a detailed TOC, tables and figures, an index, chapter or sectional cues in the headers or footers, and appropriate cross references.
Today in online docs, those handles have become live links. But the job of making the material accessible is still the same!