This is an update of a post that originally appeared on March 18, 2016.
Writing is all about emotion—I’ve mentioned this need quite a few times in the past. There are many ways to create emotion in technical writing. Of course, word choice, sentence structure, and other tools of the trade come into play, just as they do for every other form of writing. However, one of the approaches that is truly different in technical writing is the use of notes, tips, and warnings. In all three cases, you create a single paragraph sidebar-like structure, but the emphasis and nuance of the inclusion is different from other sorts of writing:
- Notes: Information that you want to include as an aside to the main text. You might choose to document the information source, the location of additional information, or augment parts of the main text in some way. The emotional impact of a note is the feeling of being special. When the reader sees a note, it should evoke a feeling that this is peculiar or extraordinary information that could impact the reader’s use of technology.
- Tips: Information that is extra in nature. You might choose to include a personal technique that you haven’t seen documented anywhere else, the location of goodies that won’t necessarily affect the reader’s use of technology described in the book, but will add to the readers appreciation of that technology, or some sort of gift-like source, perhaps a free download. The emotional impact of a tip is one of surprise. When a reader sees a tip, it should evoke a sense of getting extra value from the book—something unexpected that adds value to the reading experience. A reader should get the tingly feeling that one gets when receiving an unexpected present.
- Warnings: Information that is dire in nature. Reserve warnings for those times when a reader’s incorrect action could cause personal, data, or other sorts of damage. The emotional impact of the warning is dread. The reader should see a warning as a notification that incorrect actions are rewarded negatively—they’re the stick that goes with the carrot of notes and tips.
It’s important to remember that these three constructs aren’t the main event. Your body text is still the main event and these three elements serve only to emphasize that material in some way. Depending on the book you write, you may have other specialized paragraphs at your disposal. Each of these unique paragraph types should evoke a particular emotion. Unfortunately, the emotion they should evoke is seldom documented, so you need to figure it out for yourself. It’s essential that you do take the time to discover what emotion the paragraph is supposed to evoke (or simply not use the special paragraph in your writing).
Keep notes of what you do and why you do it. When working with various kinds of special writing, you want to be sure that the emotions you evoke with unique paragraph types is consistent across your various publications, especially if those publications are all from the same publisher. Create a style guide of a sort for yourself that contains these notes to yourself so that you can find them easily. Organizing your style guide for easy access is also a plus (which means your style guide should appear in digital, rather than paper, format.
Unlike sidebars, notes, tips, and warnings are rarely more than a paragraph long. You could possibly make an argument for two paragraphs in rare circumstances. The paragraph should contain two or three sentences with the first sentence providing a summary and the second providing details. A third sentence provides ancillary information as needed. The structure and content of your special paragraph should reflect the kind of paragraph you’re creating—as with a good actor, keep your paragraph in character. After all, it’s a performer on the stage of your book and presents the reader with a special feature that is unavailable elsewhere.
Using the special paragraphs at your disposal in the correct way can mean the difference between communicating effectively with your reader and losing the reader’s attention completely. Let me know your thoughts about the use of notes, tips, warnings, and other special paragraphs at [email protected].