To a certain extent, I agree. There are many phrases that roll off of our tongues that have no meaning and contribute no value to the reader. My earlier column on meta-talk was about unnecessary words, for instance. For most of these glorious phrases, there is a shorter (more concise) phrase that says the same thing though it sounds much plainer:
"At this point in time" ---> "now"
"In the matter of x" ---> "About x"
Some of these glorious phrases can be eliminated altogether: Nothing needs to be said at all.
Perhaps the best candidate is "Note that" as in "Note that you must turn on the water." I've edited several articles where, it seemed, every second paragraph began with "Note that". At best, "Note that" is the wordier version of the exclamation mark: Use it too often and it loses its meaning (I tell authors that they get--at most--one exclamation mark per article: use it wisely).
But I don't think that approach goes far enough: Unlike the exclamation mark, "Note that" is never appropriate and usually offensive. "Note that" points out the egoism of the author. It suggests that (a) the reader is incapable of noticing the importance of what the author is about to say and will not put the appropriate value on it, and (b) that if the author says that the following information is important then that's all the direction that the reader needs to establish the value of the information. Rather than try to impose his or her (or its) will on the reader, the author is far better off to omit "Note that", tell the reader why this particular fact is important, and let readers draw their own judgments.
Of course, that strategy will require more words than just "Note that." This is where the argument for concision falls down. The goal is not to use the fewest words possible; the goal is to cover all of what the audience needs....and then stop writing. Not just write in fewer words--stop writing altogether. It's "concision of content" that matters first; "concision of individual words", while certainly worthwhile, is (relatively) unimportant.
Reading or read
- The Case of Lena S. by David Bergen
- Small Beneath the Sky: A Prairie Memoir by Lorna Crozier
- Pandora in the Congo by Albert Sanchez Pinol and Mara Faye Lethem
Posts
2 comments:
I don't know if I'm agreeing or disagreeing with you, but I can tell you I've read (nay, studied - meaning read once for familiarity, read twice for highlighting key text, and read a third time to skim the highlighting for mastery) more than 12,000 pages of technical books over the past several years. And I can tell you from a reader's standpoint "Note that" is not nearly as offensive or annoying as you may think.
It is most useful when reserved for pointing out (non-intuitive and especially not otherwise documented) "gotchas" that may escape the attention of many readers and it is very effective when so used, in particular for those gotchas which crash the particular example code given in the book or prevent it from running. Such text should be visually highlighted in a consistent manner through the book so that it stands out easily in the page layout.
A sufficient use of such explanations of course implies that the author has conducted a certain amount of "real world" testing of the example code by typical readers to know what common errors and false assumptions the reader is likely to make when attempting to run said code.
In fact, I can say that when going back to re-read material later to look something up (which I always do - sorry I can't memorize 12,000 pages of anything even material which I have mastered and have been certified on), any such special notes called out by the author (along with my own similar notes handwritten in the margins to compensate for the author's neglecting to provide necessary Note this text) are the very places I look to first when refreshing my memory about a particular command, function or syntax.
Best regards,
Bob Schmidt
Bob:
At 12,000 pages you should be the test case for everything that I write in this column! Given your feedback I wonder if I just wasn't clear that what I objected to was the two words "Note that", not the act of highlighting critical information.
Using your example of the non-intuitive item that will prevent your program from running (and following up on your comment that it "should be visually highlighted") my objection would be to the author who writes any of these three statements:
* Note that you should always ...(content)...
* Note that you should always ...(content)... otherwise your program won't run
* Note that your program won't run unless you ...(content)...
Instead of any of the above, I suspect that, (for both of us) we'd prefer if the author consistently did something like this:
Your program won't run unless ...(content)...
By highlighting the reason/problem, the author would support me scanning the text when I'm looking for this information (particularly important if the reason I'm looking for the information is because my program current isn't running). But my clain is that putting the words "Note that" in front doesn't add anything to the visual highlighting (and the repeated use of a stock phrase like "Your program won't run unless"). In fact, adding "Note that" just delays me getting to the information by two words. It also means that dissimilar sentence ("Your program won't run", "Your computer will crash", "You will run out of memory") all begin with the same two words "Note that".
Post a Comment