-
Thanks for Reading
With the column of June 1, “The Final Why,” The Why of Style has concluded a two-year fortnighly run. Any future columns will be occasional. My e-mail address remains open for questions and comments: . Thanks for reading, and particular thanks to those who wrote in from time to time. — Mark L. Levinson
More... -
The Final Why
“When we didn’t have a manual yet, when we didn’t know what to name the commands on our menus, when we needed our business cards spelled right, we couldn’t have done without you,” the boss said. “But now the product is in release, and I don’t see the ROI from fine-polishing the error messages.”
More... -
Zero-Based English
I’ve run into people who make a virtue out of ignorance. On both sides of the fence. Some are technical writers and they say, “Because I know nothing about your product, I can serve as a model of the user’s point of view.”
“But you’re nothing like our users,” say the technicians, “because you’re not in the same business.” Then they tell the writer, “Because my English isn’t very good, my writing can serve as a model of how to write for people whose English isn’t very good.”
More... -
Reg and T.M.
There are three kinds of trademarks: our own trademarks, trademarks of other companies we like to be on good terms with, and trademarks of other companies we don’t care about. We demand respect for our own trademarks, we give respect to the trademarks of other companies we like to be on good terms with, and hey, we don’t much care about trademarks of other companies we don’t care about.
More... -
Can it be both raw and right?
“You know you guys are crazy?” said old Genady. “You tell one person that the way you write the material makes it right or wrong, but you ask another person to tell you whether it’s right or wrong before you’ve written it correctly and you’re angry that he tries to correct the writing.”
More... -
Deplorable Plurals
Writers who find the word “and” overused substitute “along with,” “in addition to,” “not to mention,” “as well as,” or “besides,” without realizing that each of those substitutes has its own connotation and none of them has the power of creating a plural.
More... -
“Such As” and Suchlike
Kipling mentioned “such boastings as the Gentiles use, or lesser breeds without the Law.” In other words, only a certain kind of boasting. But if he had written “boastings, such as the Gentiles use,” it would include all boastings and those of the Gentiles would be just an example.
More... -
The Tense for What Never Happened
It makes sense to say “I’ve never seen such a beautiful view.” But there’s a complication. If I’m looking at such a beautiful view right now, how can I say I’ve never seen one?
More... -
Too Much Determination
I knew I couldn’t put across an explanation, but perhaps I could at least put across the impression that I think I know what I’m talking about. “It comes down to a difference between English and Hebrew,” I said. “The word ‘it,’ in the objective case, can serve as a relative pronoun in Hebrew but not in English.”
More... -
The Multi-Tailed Example
You try to write the example so that it reaches out a well-directed hand to the reader, and the reader grabs the example by the tail.
More... -
Don't Overshorten
-
The Wherefore of Style
I ask about the purpose, and I’m answered about the background. “Why do the user’s neckties appear on the screen in that particular order?” I ask, expecting to hear how that particular order serves the purpose of benefiting the user.
“They appear according to the sequence in which they arrive from the database,” says Dror the developer.
More... -
The Andor and the Orboths
-
Forever HIPO
Before you set about doing something, you should know what you’re starting with, what you’re planning to do to it, and what you expect to wind up with at the end. And that pattern of input, process, and output is hierarchical.
More... -
Unstating the Obvious
Granted, writing needs to acknowledge the known, at least tacitly, in order to stably introduce the unknown. But still, every sentence - even the first one - should add informational value if possible.
More... -
Time for an Update
Before the progress bar reached 100 percent, I wrote the preceding thirty-two editions of this column. Now that they’ve all appeared, it’s time for an update because in the meantime some e-mail has come in.
More... -
The Phrasals and the Had Had
Who cares what’s a phrasal verb and what isn’t? In my experience, the only people who care are people looking for an excuse to end a sentence with a preposition. And they’re wasting their time.
More... -
Necessary Unnecessary Facts
In order to write correctly what you know, you need to know more than you write. Hemingway said, “When a writer omits things he does not know, they show like holes in his writing.”
More... -
The Overgrown Dash
The em dash was not just left off the keyboard. While no one was looking at it over on the upper-ascii sidelines, it was sabotaged..
More... -
The Tommy Syndrome
Tommy, in The Who’s rock opera of the same name, achieved spiritual enlightenment after psychosomatically losing the powers of hearing, sight, and speech, so he tried to tell his disciples all to “Put in your ear plugs, put on your eye shades, you know where to put the cork!” The Tommy Syndrome is everywhere.
More... -
When Numerals Come 1st
Even the 4-H club tries not to start a sentence with a numeral, and imagine how difficult it must be for them. But is there logic behind the rule?
More... -
The WhyNot of Style
Before you correct what another of God’s creatures has written, it’s your responsibility to be sure you’re reacting to a real, explainable flaw and not merely to a difference from your personal style.
More... -
Go-Back-Again Words
I can’t compare the reading of a sentence to the grubby exertion of picking up bullet casings (not most sentences, anyway) but there can be a similar disappointment when you reach the end and you need to go back over the whole thing again.
More... -
Life as a Computer
To anthropomorphize means “to attribute a human form or personality to” (Webster’s, 1913). Never anthropomorphize computers. They hate it.
More... -
The Responsible “We”
Just as you would define any acronym on first use, it’s best to define who “we” is - “we at Neckwear Techware Limited,” for example - and to stay true to that definition.
More... -
Weak and Strong Commas
If you have commas serving more than one purpose in the same sentence, it’s a good idea to consider whether all the commas are necessary.
More... -
Forcing a Comma
Because everything depends on the division between subject and predicate, sometimes a writer is tempted to mark that division with a comma. Particularly if the subject is long, or weighty, or followed by a pause when you speak the sentence, or if the subject is full of internal punctuation itself, or if the end of the subject isn’t obvious at a glance, the devil will offer you a comma as a tool of clarification.
More... -
Left and Right Commas
If commas came in left-hand and right-hand versions, like parentheses, quotation marks, and Spanish question marks, then I think writers would be less likely to leave commas without their mates. For example, some writers - possibly fearful of comma clutter - use a comma before a year but not after it.
More... -
The Days of Wine and Charoses
The important principles of technical writing are already present in the Hagaddah, the venerable promptbook for the Passover meal. We moderns have invented nothing.
More... -
Collaboration
The elevator door chimed open and Mumpy stepped out. Maybe she knows a good graphic artist, I thought. I needed to produce a brochure for the TiePlumb computerized necktie straightness gauge.
More... -
The Yucan, Your 2nd-Best Friend
When I receive a document from R&D, it’s easy to tell whether Dror wrote it or Liora did. Dror is an allower, whereas Liora is an enabler.
More... -
Repetition, the Forbidden Tool
In technical writing, one of the basic challenges of the print medium is that its nature is linear while the nature of the topic — of the product or process — may have more to do with a hierarchical or random-access structure. Often what makes repetition seem called for is the attempt to force a non-linear structure into a linear one.
More... -
Re-logonning
There isn’t a single dictionary on http://www.onelook.com that lists “log onto” or “log into.” However, in usage “onto” and “into” are fairly strong. On Google, “you log in to” versus “you log into” is 549,000 to 488,000.
More... -
With Regard to Worth
I was sent to the class next door, where I asked the neighboring teacher for “two people’s worth of plasticene.” She laughed.
More... -
Archived Articles
List of archived episodes of The Why of Style. Only visible to Elephant members who login. You can apply for membership at http://www.elephant.org.il/faq_and_application/application_form.htm
More... -
For Fewer Parentheses
If the parenthesized remark is a less important point or an afterthought, the end of the paragraph is a fine place for it to stand out in the open, like a modest hut on the beach with the whole city of sentences on one side and the echoless edge of the island on the other.
More... -
The Dictionary as Doberman
The dictionary pretends to be a conscientious follower but, like a hundred-pound Doberman being walked on a leash, it can’t be led anywhere it doesn’t want to go. The word “seperate” has more than nineteen million hits on Google but no dictionary recognizes “seperate” as a legitimate spelling.
More... -
Is the Colon a Multiplexer?
Colons are like piercings. Back in the day, they had their strictly prescribed positions and you seldom saw them anywhere else. Now people insert them all over the place.
More... -
Eyecatchers and Eyedodgers
When you’re intently reading pages of 10-point type, your eyes may not bother to readjust for those few words of big print. Your brain may not bother to adjust from absorbing low-level exposition to absorbing a high-level concept.
More... -
Writing Against the Future
The point is to think what might happen in the future. And I’m not talking about puzzled scholars in the year 6000 wondering what kind of a tube was a YouTube. I’m talking about the customers of your product’s next version.
More... -
Hebrew Isn't All Bad
As a naive new immigrant, I would say to people “How are you?” in Hebrew, translating literally. They looked back at me as if I had asked “Why are you?”
More... -
Space Resurgent
The screen of the 1970s gave us 24 lines of 80 characters each, which continued to encourage compressing the message. Only recently have we started to see high resolution, big screens, and with them a re-emergence of white space.
More... -
Words That Want Too Much (2)
A fable: In its youth, the word However was just another member of the Ever family, like Wherever and Whoever and Whichever. They all had simple meanings.
More... -
Words That Want Too Much (1)
When I was young, and English was English, or at least it was American, “multiple” meant only one thing.
More... -
Heroism and Minimalism
I suppose it’s unusual for a technical-writing department to have a slogan, but when I worked at Daisy Systems the department had a slogan: “The user is the hero.”
More... -
Is it an If or a Lest?
Here’s an expression to drive you crazy: “in case.”
“Just in case there’s a fire, we keep a bucket of sand handy.” We keep the sand handy whether there’s a fire or not, because some day there might be one.
More... -
When Not to Be Interesting
Some writers labor to keep their sentences uncluttered but clutter their examples with items that are distracting or even dangerous. If an example calls for a list of usernames, they’ll list their favorite basketball players or favorite fictional characters. But your favorite basketball player sells his name for use on sport socks for millions of dollars.
More... -
This and That
The old preacher’s advice goes, “Tell them what you’re gonna
tell them, then tell them, and then tell them what you told them.”
More... -
Opening
When you start reading the TiePlumb User Guide, be it a booklet or a help system, what should the first sentence say to you? I’ve seen some first sentences that say “Welcome,” I’ve seen “Thank you,” and I’ve even seen “Congratulations.”
“Welcome” is supposed to sound friendly, but to me it sounds arrogant and inaccurate. It says, “You are in our territory now. We are the proprietors and you are the disoriented stranger.” Wrong message.
More...
Upcoming Courses
- Developing a Documentation Style Guide
Nov 24 2008 - Single Sourcing with FrameMaker
Nov 27 2008 - Building a Front-End Interface to Document Collections
Dec 02 2008 (09:00 - 13:00) - Using Captivate to Create Video Demos (enhancing software documentation)
Dec 11 2008
Summaries