Tag: Warnings

Using Notes, Tips, and Warnings Effectively

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].

C++ Data Type Usage

This is an update of a post that originally appeared on October 16, 2015.

Originally I provided this post to correct an example in a previous edition of the book. Now I’m providing it to clarify that same example to a greater degree and answer reader input. The Going Overboard section on page 64 of C++ All-In-One for Dummies, 4th Edition talks about the problems that can occur when you try to stuff a number that’s too large into a specific data type. The problem with the example shown:

cout << 12345678 * 100 / 2 * 3 * 3 << endl;

is that while it does display a warning message, the warning really doesn’t get the point across. In order to see the example as originally intended, you need to change the code to read:

long MyLong = 12345678 * 100 / 2 * 3 * 3;
cout << MyLong << endl;

The code will now produce a warning and you can see why in a clearer way, just as described in the book, because the data type isn’t ambiguous any longer. In both cases you see a warning message of:

warning: integer overflow in expression of type 'int' results in '1260587804'

One of the ways to overcome this problem is to ensure that you use the correct sized variable in the first place. The following code doesn’t produce a warning message because of the use of auto (telling the compiler to choose the correct variable type automatically) and ll (telling the compiler to use a long long variable for the calculation).

auto AutoSize = 12345678ll * 100 / 2 * 3 * 3;
cout << AutoSize << endl;

A number of readers were happy that I pointed the problem out, but wanted to see a fix for the problem as well. When you run the example with the additional code, you see outputs of:

1260587804
1260587804
5555555100

Only the third answer is the correct one and it points out the need to pay attention to both warnings and errors as you code. Please let me know if you have any questions or concerns about this example at [email protected].