I like this "blog"

Ken Olsen sent a link to "this" blog. I'm "happy" to "share" it with "you":

Are we evil for calling Inuit people "Eskimos"?

By way of a link from Lydia McGrew, we find John C. Wright's objections to political correct speech:

I am aware of that [the origin of the word "eskimo"], and I do not care. In fact, I regard with particular hatred attempts to change the language to sooth the imaginary hurt feelings of various mascots of the political Left. Unless you can tell me, off the top of your head and without looking it up, the name in any Eskimo dialect for a Virginian, I suggest your concern for their concern for our names for them is illegitimate, particularly where no English speaker knows the meaning of the insult. (None, that is, but I: it refers to them as eaters of raw fish, a slight against their relative poverty).

Besides, what could be more insulting to me that to have the Eskimos refer to themselves as ‘the People’? What does that make me? A non-people?

But it would be immature to the point of insanity for me to pretend I am insulted by the mere existence of a word in their language. Likewise, here. Insult requires intent.

I ask any and all reader please to not make corrections of this type again. They offend me. They deeply offend me. [. . .]

Let me explain that I regard political correctness as worse than a lie.

A lie is a straightforward attempt to deceive a victim. It almost honest by contrast. Political Correctness is a corrupt attempt to poison thought and speech, and to impose upon the nobility and courtesy of its victims to get them to deceive themselves. A frequent side effect of PC jargon is that it renders rational conversation difficult, indirect, or even impossible.

Innocent and well meaning people are actually fooled by this simple trick. Sad to say, most people think like magicians. They believe in the rule of true names. They think (or rather, they feel) that when they are calling one thing by another name, that the actual nature of reality changes. They put themselves in a position where they can no longer talk about real things. Words are severed from referents.

Words really do have power, but not in a magical sense. Words have power because we use words to describe our own versions of reality. Being forced to substitute other peoples' words to describe your own reality is to allow those other people to not only influence but in some ways to control your reality.

If you successfully substitute the word 'Inuit' for 'Eskimo' on the grounds that 'Eskimo' is an insult, you will have successfully convinced the next generation that all their forefathers who used the word 'Eskimo' deliberately meant and fully intended an insult, or were foolish or negligent enough to utter an insult by accident. That conviction will be false, a lie, and you (in a small way, one more straw on the camel's back) will have helped to perpetrate it.

Exactly. While I do not agree with everything Mr. Wright discusses in the rest of his post, I can't find fault with the sentiments quoted above.

Lydia also included a link to P.J. O'Rourke's wonderful review of Guidelines For Bias-Free Writing (PDF):

The book arrived with an I.U. press release stating that, I quote, Anyone who spends even a few minutes with the book will be a better writer. Well, I spent a few minutes with the book, and I feel a spate of better writing coming on.

The pharisaical, malefic, and incogitant Guidelines for Bias-Free Writing is a product of the pointy-headed wowsers at the Association of American University Presses who established a Task Force on Bias-Free Language filled with cranks, pokenoses, blowhards, four-flushers, and pettifogs. This foolish and contemptible product of years wasted in mining the shafts of indignation has been published by the cow-besieged, basketball-sotted sleep-away camp for hick bourgeois offspring, Indiana University, under the aegis of its University Press, a traditional dumping ground for academic deadwood so bereft of talent, intelligence, and endeavor as to be useless even in the dull precincts of midwestern state college classrooms.

But perhaps I’m biased. What, after all, is wrong with a project of this ilk? Academic language is supposed to be exact and neutral, a sort of mathematics of ideas, with information recorded in a complete and explicit manner, the record formulated into theories, and attempts made to prove those formulae valid or not. The preface to Guidelines says, “Our aim is simply to encourage sensitivity to usages that may be imprecise, misleading, and needlessly offensive.” And few scholars would care to have their usages so viewed, myself excluded.

Remedial Headline Writing

The headline on a recent article in PC World includes an eye-catching statistic:

IT Pros Find Smut on 3 out of 4 Employee Laptops

My first response was "so few? Really?" (but I'm pretty cynical about things like that). After reading the first paragraph, it became clear that whoever wrote the headline didn't really read the article:

Nearly three-quarters of corporate security and IT professionals in the U.S. have found "inappropriate" pictures, videos or browser cache links on employee laptops, a survey released Wednesday shows.

A more accurate, but less sensational headline would not have confused the proportion of IT staff finding "smut" with the proportion of employee laptops containing "smut". So, it is not that three out of four employees have "smut" on their computers, but that three out of four IT staff members have, at one time or another, found "smut" on other employees' computers. Rather a significant statistical difference, no?

Now the statistic implies that one in four IT professionals aren't doing their jobs properly!

"Heretic! Heretic! Burn him!"

Geoffrey Pullum decides that things are too quiet in his life, so he pulls out his copy of The Elements of Style, pours on generous amounts of bile and lights a match:

April 16 is the 50th anniversary of the publication of a little book that is loved and admired throughout American academe. Celebrations, readings, and toasts are being held, and a commemorative edition has been released.

I won't be celebrating.

The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students' grasp of English grammar; it has significantly degraded it. [. . .]

This was most unfortunate for the field of English grammar, because both authors were grammatical incompetents. Strunk had very little analytical understanding of syntax, White even less. Certainly White was a fine writer, but he was not qualified as a grammarian. Despite the post-1957 explosion of theoretical linguistics, Elements settled in as the primary vehicle through which grammar was taught to college students and presented to the general public, and the subject was stuck in the doldrums for the rest of the 20th century.

Notice what I am objecting to is not the style advice in Elements, which might best be described the way The Hitchhiker's Guide to the Galaxy describes Earth: mostly harmless. Some of the recommendations are vapid, like "Be clear" (how could one disagree?). Some are tautologous, like "Do not explain too much." (Explaining too much means explaining more than you should, so of course you shouldn't.) Many are useless, like "Omit needless words." (The students who know which words are needless don't need the instruction.) Even so, it doesn't hurt to lay such well-meant maxims before novice writers.

It's been a while since this sort of heresy was bruited about the intertubes. It could get entertaining, for a while.

PowerPoint's worst presentations

I'm not generally a fan of PowerPoint, but I have to admit that I haven't seen many presentations worse than these eyesores:

Sample from Alexei Kapterev's "Death by PowerPoint" presentation"

Dumbing down street signs

Frequent commenter "Da Wife" sent me this link with the comment "Are you sure these people were not educated in the Canadian school system?" and "Everything is [being] dumbed down so the stupidest do not feel left behind":

It may soon be a little easier to mind your pea's and queues in Birmingham.

Or so think the British city's politicians, now that they've decided to ban all apostrophes from street signs, on the grounds that they're fussy, old-fashioned and confusing.

For decades, apparently, residents have been embroiled in heated debates around punctuation in signs for such local landmarks as St. Pauls Square or Acocks Green.

A verbal donnybrook on whether Kings Heath should be rewritten with an apostrophe proved to be the last straw for Councillor Martin Mullaney. "I had to make a final decision on this," he says. "We keep debating apostrophes in meetings and we have other things to do."

It's sad, really. The idiot politicians probably feel they're doing the right thing . . . if they're spending time in their meetings debating fine points like whether an apostrophe is required, wouldn't it make sense to consult an expert? Does the council not have access to English teachers?

A Firefox review

Jon, my virtual landlord, had to troubleshoot some problems with Firefox the other day. This is the non-confidential part of the summary:

Just a note to let you know that I have installed the latest version of WebWorks Publisher and have created some test output. The Firefox problem with the "initial" links in the Index is still present — clicking on a letter at the top of the Index pane does not jump to the corresponding section in the Index.

It works in IE 7.0.5730.13, Chrome 1.0.154.36, Opera 9.25, and Opera 9.63 (but with some display issues due to how Opera interprets table cell backgrounds). I also tried it on Linux (Knoppix) and found that it works on Konqueror 3.5.5 and Iceweasel 2.0.0.1.

My analysis: IE, Chrome, Opera, Konqueror, and Iceweasel are fine browsers, crafted with care and an impressive commitment to professionlism and compatibility. Firefox is a fetid swamp of bugginess, plagued with poor code written by guys who probably have trouble finding their way home at the end of the day. Actually, that last part most likely is not true; they have no problem finding their way home at night because they have never left home; they still live in their mother's basement, where they spend their time writing sloppy code. One can imagine their pathetic simpering as they chortle to themselves with every release: "Ha ha ha! Look what I am going to do to thothe WebWorkth Publisther utherths!"

If he'd included a reference to shit waffles, he'd be getting a call from Ben "Yahtzee" Croshaw about intellectual property infringement.

A modern update to Strunk & White

Just when you thought it was all randomly generated, we now discover that those entertaining offers of erectile dysfunction drugs, pornography, and free electronic devices actually do follow a formal style guide:

Elementary Rules of Usage

1. Form the possessive of nouns by adding 's, just an apostrophe, just an s, a semicolon, a w, an ampersand, a 9, or anything.

My wifesd*porcupine hot pix for u.

11. A participial phrase at the beginning of a sentence must refer to the grammatical subject.

Upon receiving this couppon, the free iPOds will greet you!

The introductory phrase modifies you, not iPOds; therefore, it is necessary to recast the sentence.

Upon receiving this couppon, you will be greeted by the free iPOds!

Or, better still (see Rule 14).

This couppon entitles you to greetings from the free iPOds!

H/T to Stewart Dean.

Historical font-fondling

For more than you ever wanted to know about the Helvetica font and the New York City subway system:

There is a commonly held belief that Helvetica is the signage typeface of the New York City subway system, a belief reinforced by Helvetica, Gary Hustwit’s popular 2007 documentary about the typeface. But it is not true — or rather, it is only somewhat true. Helvetica is the official typeface of the MTA today, but it was not the typeface specified by Unimark International when it created a new signage system at the end of the 1960s. Why was Helvetica not chosen originally? What was chosen in its place? Why is Helvetica used now, and when did the changeover occur? To answer those questions this essay explores several important histories: of the New York City subway system, transportation signage in the 1960s, Unimark International and, of course, Helvetica. These four strands are woven together, over nine pages, to tell a story that ultimately transcends the simple issue of Helvetica and the subway.

QotD: Documentation

I have encountered far too many managers who couldn't recognize bad documentation at all. Until the flaws are pointed out to them, or they compare it with good documentation, they are oblivious. That is why there are also far too many people working as technical writers who should be wearing greasepaint and ruffled collars instead. Those of us who are competent should be continually educating our co-workers and managers by pointing out excellent examples of technical communication.

We have a lot of fun commenting on the bad examples, but I think we should be showing off the good ones much more than we do now.

Beth Agnew, posting to the Technical Writing mailing list TECHWR-L, 2008-05-15

The nature of guilds

In a discussion on the technical writing mailing list earlier this week, someone proposed trying to organize technical writers in some form of union or guild. Kevin McLauchlan tackled the idea of a guild head-on:

Doctors and lawyers don't often work in groups of hundreds or thousands, but their guilds regulate them (a little) and keep their clubs exclusive (sorta), and collude with government, thereby keeping membership numbers controlled and prices up. For example, [in Ontario] the medical association just graciously "permitted" a new medical school to come into existence.

The other side of that is that they've been not permitting some/many to come into existence. This, in a province and a country that is becoming desperately short of doctors. Here in the land of socialized medicine, a large (and rapidly increasing) percentage of the population does not have a family doctor, simply because there are not enough licensed doctors to go around. Instead, people use the hospital Emergency room for every medical need, or they go to walk-in clinics (where they rarely see the same doctor twice . . . but at least some records are kept . . . but they don't always go to the same clinics because. . .)

Clinics are closing, or are going on reduced operating hours because they can't find doctors to work the time-slots. Lots and lots of our doctors (including my own GP) are foreign-born and foreign-trained, but many foreign-born, foreign-trained doctors are working as taxi drivers or other occupations because they are not permitted to practice medicine in this place that is so desperately lacking doctors.

Between government (that gives them the clout to enforce) and the medical association that does the enforcing, the number of doctors is kept artificially low. The newly arrived doctors from India, Malaysia, Arab counties, Eastern Europe, etc. are not permitted to become Canadian doctors. Part of the excuse that's given is that their skills need to be harmonized with the Canadian medical standards of practice . . . but there are not enough resources to process most of the applicants. But the lack of resources lies directly at the doorstep of the /g/u/i/l/d/ Medical Association that sets the numbers of med-school seats, the number of med schools that can be accredited, the number of programs and personnel that can mentor and supervise immigrant doctors until they get up to speed.

That kind of power and impunity can exist only when you've got government in your corner, supplying the legal clout to make your /g/u/i/l/d/ association pronouncements carry the force of law. The results are kinda harsh, when the turnaround time for a change of priorities is a matter of years or decades.

So, STC (or some other techwriter guild) would need to get government on-side in order to set quotas and price guidelines that could be enforced on the hundreds of thousands of companies that employ us in onesies, twosies, and small groups. They'd also need to enforce requirements for our services. Unlike engineers, we provide services that can be dispensed with, or that can be offloaded to non-professional, non-accredited techwriters . . . unless the law says that any product that is sold must be accompanied by documentation that carries the <STC?> seal of approval . . . having been created by <STC?> accredited writers. Of course, that kind of requirement would drive even more production offshore. Unlike the provision of medical services, product development and production can be done very far away from the people who eventually purchase the product.

QotD: Words that don't exist, but should

Straternization: Hanging out socially with people not because you like them, but for their strategic benefits (i.e., helping you get ahead in work, getting you closer to that cute young thing, raising your social status in the lunchroom, etc). Usually doesn't work nearly as well as people hope.

John Scalzi, "Today is International Make Up a Word Day", Whatever, 2008-02-27

Salaries in the writing field

I've always told folks that technical writing pays far better than creative writing for the vast majority of writers. For every J.K. Rowling in the creative field, there are tens of thousands of aspiring writers who can't earn enough to support themselves. Someone has kindly pulled together the figures for various writing jobs, including technical writing, and it mostly supports my contention.

This is a list of the average salaries for a number of writing and editing professions. The figures represent typical scales for a mid-sized metropolitan area in the United States. Larger markets tend to pay more and smaller markets tend to pay less. Remember that these are typical salaries for people who are employed by other companies. There is a much greater income variation among people who freelance or own their own businesses.

Yes, as a technical writer, you may never see your name on the cover of the books you write, you almost certainly won't be going on glamorous book tours of exotic locales, and you'll be writing things that don't exactly engage the most creative portion of your brain. But you'll be relatively well-paid, work in reasonably comfortable conditions, and have a pension or some other form of retirement savings for your post-writing lifestyle.

I've never met a rich technical writer, but I've met many, many starving creative writers.

If you're really clever, there might even be a way of leveraging your technical writing career to, I don't know, maybe even support your creative writing habit until that multi-million dollar advance comes in for your next novel.

I guess it could be worse . . .

In the glamorous, high-tech, fast-paced world of technical writing, we sometimes run into situations where we have to document around software or hardware problems. It's the sort of thing that marketing might try, in the sense of redefining a bug as a "feature". But it could be much worse, if you're developing custom software for a client:

[The client] would buy new hardware and software, but it had to look and function exactly like the old systems. No touch-screens, no graphics and no cashier-friendly reminders; just a plain old text-based interface with obscure keyboard commands for navigation. After all, they had spent a lot of money developing training programs for these registers and had no intention of simply throwing them out.

The retailer had also invested in a whole host of back-office management and reporting applications. Some were PC-based and some relied on proprietary hardware, but they all interfaced with the old cash registers' proprietary database. And though many of those applications were antiquated as well, the retailer had no desire to retire them. The new software would just have to interface with them. On top of that, the retailer didn't want a "flash cutover" deployment. They wanted a seamless, phased deployment that would allow them to switch over one register at a time, and have it all look the same on the back-end. So, with the latest and greatest technology at their disposal, Dave's team built outdated and mediocre software that functioned and communicated exactly like the old software. It did everything it was supposed to do and it did it right. And therein lay the problem.

Shortly after they delivered the software, the retailer rejected the QA testers' build and sent David's company a list of bugs. But it wasn't a list of bugs that their software had — it was a list of bugs that it didn't have. When the retailer said they wanted the same functions, they apparently meant the same bugs as well.

A word to the Word-Wise

It's been many a long year since I last had to struggle with Microsoft Word (aka "Microsoft Weird"), especially with the master document feature. This is a seemingly useful way to incorporate several individual MS Word files together into one book or volume. It's also the easiest way to force yourself to recreate your documents from scratch, as the feature is notorious for corrupting the documents you include into your master document. This FAQ exactly captures the situation with MS Word master documents:

When we say you "lose" your master document, this "loss" can take many forms. You wouldn't be reading this at all if you had not so far experienced one of the lesser forms. You can still read "some" of your text, right? Trust me, it can get worse! The ultimate master document corruption results in some or all of the text paragraphs disappearing. Once this happens, there is no way to get them back: they are no longer in the file. Which can be very disconcerting if the corruption happened several weeks ago, and because you were not looking at that part of the document, you didn't find out about it until you came to print the whole thing, by which time you had long since over-written your backup!

A master document has only two possible states: Corrupt, or just about to be corrupt. And that is why we say that the only possible fix to a master document is "don't use it!"

Employment hurdles for the miseducated

A few screamingly funny examples of actual cover letters received by Killian Advertising:

"Skills: Microst word, excel, and power point. Mulitaks person, public speaking, and surveying.
Professional Associations
Chairwomen of Studnts Teaching Awareness and Responsibility organization Responsible for research of all 10 event topics, coordinating all campus chiarpersons."
[Editor's note: Despite the many and obvious limitations of SpellCheck, isn't it worth at least a try ... for instance, while you Mulitaks with the other chiarpersons?]

"Who's better to spew out incite, than a college senior ... ?"
[Editor's lament: We don't have the "imaginatiation" to make up stuff like this.]

An all-time classic sent in by a CLFH fan from the great state of Michigan, where the cyclical nature of the automotive industry leads to a lot of job switching. It's yet another example of why you can't just rely on spell-check to catch all your errors:

"I am seeking a new position as i have recently been laid."
[We wish her the best of luck in her career.]

"I need real world experience and after reviewing your web site I get the impressing that your company believes in maintain a lax work environment while efficiently meeting the needs of it's customers (right?)."
[We replied to this college senior, on an ill-advised rescue impulse, gently suggesting he get some remedial help with his writing, since he had an error in every single sentence of his three-page letter. His furious four-page reply included some amazing stuff, such as]
"...you should be straight forward and ... simply state that your company is seeking a grammar teacher who lacks creativity but knows how to properly write a letter and knows exactly where to place punctuation. If your company takes such a serious position towards proper grammar then I think you guys are in the wrong profession. I believe even the leader of this country that we live in lacks proper grammar yet he is still our leader. I can assure you that he leaves grammar and punctuation to the proper authorities such as his receptionist or grade school English teacher. ...I am not precisely sure why you choose to take such a stance perhaps because you have nothing better to do, or maybe because you have personal insecurities that seep out and you feel the need to degrade or target others based on stupid little infractions to make yourself feel better, I don't know what the case is ... if I am out of line please let me know but if I recall properly your companies web site is not the most professional site there is. If you guys are trying to project a laid back yet hard working image through your site and request the same from prospective employees then you should not be so prudent about minor infractions such as punctuation and grammar.... (I reread it before sending it and it states my point clearly and unless you lack the mental capacity to make out the meaning without having exact and precisise grammar maybe you should seek a new proffsion, I hear this country lacks alot of grammar school teachers perhaps that would be a better fit for you) In conclusion I have indeed made many mistakes in this e-mail many on purpose and many accidentaly I did not have the time nor the patientce to deal with it I will leave the grammer checking to the professionals such as yourself."
[Editor's note: although his response fascinated us, you can understand why we no longer reply to the Differently Stable.]

And there's more . . . much, much more . . .

A response

The post quoting tekwrytr@hotmail.com provoked "Snooty McTooty" to write a spirited response (lifted out of the obscurity of the comments to that post):

As a snooty technical writer myself, I have a few issues with this post.

The author states, "If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency."

That's a no-brainer. I think we can all agree that the quality of instructional content is far more critical than the style, form and consistency of the writing itself. I don't think any technical writer would argue otherwise. Although many technical writers serve as their own editors, the processes of writing and editing are distinct. Although it is good to keep style, form and consistency in mind while writing, they are all things to double check during the editing process. The goal of technical writing is to clearly communicate technical information to a (typically) non-technical audience. The only way to achieve that goal is through quality instructional content. Duh!

Also, I think we can agree that as long as humanity creates inherently unintuitive things (from software to garage door openers) there will always be need for clear, concise operating instructions, and thus a need for technical writers. Implying that the future for technical writing is somehow threatened, outdated, or unnecessary is alarmist and absurd.

The author states, "Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance."

Then why do any of us continue to be paid for our services? If the work product was always horrendous, why is there still a need for it? I have seen many examples of quality end-user documentation.

I do agree that users are primarily interested in task-accomplishment assistance. Users don't want to read an entire manual to figure out how to perform a task at hand. If the manual has a table of contents and an index, guess what, they typically don't have to read every word of the manual. They can use an inventive device called a page number and look up the precise page of instruction relating to their task. Task level assistance can also be achieved using interactive tool tips, context sensitive help files, and in some cases simply writing out pointers on the application itself (many Web-based applications provide instruction right on the application’s page). If a client isn't willing to budget for this level of assistance or for quality documentation, it's the client's fault, not the technical writer's.

I agree that every effort should be made to facilitate user instruction; but at some point users must stop whining and read the instructions. Yes, no-one likes to read instructions. Most of us like to jump right in and start using the application or product. But after we've broken the product or get stuck using the application we eventually have to break out the instruction manual to understand how to accomplish our task.

One last note. Implying that Linux is not a widely used operating system because its documentation is confusing is an extreme oversimplification. What about the fact that Windows comes pre-installed on most PCs? What about the fact that Windows is the standard operating system for most businesses? What about the fact that Windows has a consistent and reasonably easy to understand GUI? What about the fact that Windows ships their OS with a large driver pack? What about the fact that there is a standard process for installing and uninstalling applications under Windows? What about the fact that, for typical users, maybe, just maybe, it IS easier to use Windows than Linux? Linux is languishing because of poor documentation? Come on.

Also, why abbreviate "technical writing" throughout this post? Is it that much of a burden to type out?

TWs ftw!

The bottom of the waterfall or going over the top

Given how rarely I post anything in the Tech Writing category, it's mindboggling that I've got two on the same day . . .

John Hedtke (who also blogs — occasionally — at Don't Ask Me; I'm Making This Up As I Go Along) had this to say about a few of the non-traditional software development models:

XP and Agile are excuses for bad behavior. "We're manly men who code brilliantly; we don't need documentation because our code is perfect and if the users don't understand our godlike design, that's their problem." XP and Agile will get code out the door and it may even be good code (occasionally), but it ignores the idea that 90% of programming is maintenance . . . and without internal documentation or process, you have no history.

I've seen XP happening in a number of companies that are now dead. Think of it as evolution in action.

This is not to say that there aren't good aspects to the current flavour-of-the-month software development models, but this particular interpretation of XP/Agile carries with it some built-in flaws, and the poor folks in the QA and Documentation groups are usually the first to get hit with them.

It's the design, not the documentation

There's a good discussion going on the Framers mailing list today, with this post by "tekwrytr@hotmail.com" being of particular interest:

Technical writing, specifically end-user documentation of software applications, is perceived by the majority of producers as "less than useful" and, in general, a waste of money, time, and effort. Similarly, the TW's view that they are "adding value" to a product may be just as impoverished.

Documentation is not used by the end-user because it is awkward, poorly organized, and in many cases, indecipherable for a user seeking task-accomplishment assistance. Linux is a primary example; despite some of the most dedicated, motivated developers on the planet, and droves of TWs spending endless amounts of time creating "tutorials," introductions," and "documentation," (along with a massive PR pitch by IBM a few years back), Linux languishes. Users avoid it because it is "too difficult to learn."

The underlying cause begs exploration, and is at the heart of technical documentation; does the TW really want the witless user to understand what the TW finds conceptually difficult? Or is there the same tendency in TW that is found in academia — "I took years to learn this, and you expect me to tell you how to do it in half-an-hour?"

I am not suggesting for a minute that the process is planned, or even that the TW is aware of it. I am suggesting that the underlying premise of technical documentation is not "documentation" (as in "creating a record of"), but knowledge transfer. It is in the area of knowledge transfer that TW comes up short. Of all the software documentation available on October 18, 2007, how many pieces are considered easy-to-use by users?

What I suggest is not a simplistic condemnation of TW, or TWs. What I suggest is that the underlying premises of TW may be impoverished, and suffer the same weakness as academic "instruction." That is, replaying the one-to-many lecture style of Aristotle on the computer screen, in the mistaken belief that a user really cares whether every i is dotted and every t crossed, or that a consistent style is used for all code samples, and a consistent voice is used for all explanations.

Finally, the reason that user interfaces in software applications require extensive documentation is a failure in the design and programming stage, not in the documentation stage. If the interface were competently designed, it should be "intuitive" to use, and require only minimalist documentation. If there is a future for TW, it lies in the area of facilitating knowledge transfer, rather than an obsession with style, form, and consistency.

Reproduced by permission.

Lorem Ipsum dolor sit amet

From the "I didn't know that" hopper:

What is Lorem Ipsum?
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

Where does it come from?
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32.

Source: http://www.lipsum.com/

The problem with email

Daniel Goleman points out some of the problems with email:

The advantage of a phone call or a drop-by over e-mail is clearly greatest when there is trouble at hand. But there are ways in which e-mail may subtly encourage such trouble in the first place.

This is becoming more apparent with the emergence of social neuroscience, the study of what happens in the brains of people as they interact. New findings have uncovered a design flaw at the interface where the brain encounters a computer screen: there are no online channels for the multiple signals the brain uses to calibrate emotions.

Face-to-face interaction, by contrast, is information-rich. We interpret what people say to us not only from their tone and facial expressions, but also from their body language and pacing, as well as their synchronization with what we do and say.

Most crucially, the brain's social circuitry mimics in our neurons what's happening in the other person's brain, keeping us on the same wavelength emotionally. This neural dance creates an instant rapport that arises from an enormous number of parallel information processors, all working instantaneously and out of our awareness.

In contrast to a phone call or talking in person, e-mail can be emotionally impoverished when it comes to nonverbal messages that add nuance and valence to our words. The typed words are denuded of the rich emotional context we convey in person or over the phone.

I certainly value email as a communication channel, as I can refer back to what I said or what the other person said without having to verbally re-map the conversational pathways. But the chances of misunderstandings and misinterpretations are much higher for email conversations between people who've never met in person.

H/T to Arroxane Ullman, who posted the link to Techwr-L.

Interesting new research tool

It's probably not of interest to a lot of you, but if you do any web-based research for writing, you'll want to have a look at Zotero. David Neeley sent this link to the Techwr-L mailing list with the following recommendation:

One incredibly useful add-on for firefox, by the way, is Zotero. Created by the folks at George Mason University, it is designed for online research. You can capture bibliographic data from various journal and book sites "automagically" as well as do web page captures, links, list related references, make either free-form or cut-and-paste notes, and more. Then, you can export bibliographic information in standard formats if you wish to do a formal paper.

I've installed it and started playing around with the features, and it's the sort of thing the web is made for: a well-designed tool for a specific purpose that does almost everything you could want to make that task easier. I haven't given it a real road-test, but on first inspection I'm very impressed. Give it a try.

The value of software documentation

Here's an interesting twist: sales of open source software appears to be highly linked to the quality and quantity of the available documentation:

[. . .] the vast majority of our deals are fed by two direct sources: those who read our documentation and those who actually download and try our Enterprise code. Now, we also know that most of these people first start with our Community code (and often evaluate it for months, reading documentation and visiting our website in the meantime).

What does this mean? It means that if our demand generation software is telling us that someone has both read documentation and evaluated Enterprise, the odds of them buying support from Alfresco are huge. We want to be calling that prospect immediately.

But it also means that documentation is a huge opportunity for open-source companies to drive sales. Documentation is often treated as the shabby cousin of software development, but it is really the essential link between development and dollars. It's hard to motivate good documentation.

Software development without documentation is self-centric. Documentation is a signal that the developer actually cares about her downstream users. For projects that actually want downstream users, write good documentation. It won't cannibalize buyers: it will create them.

H/T to David Neeley.

Just when you think you've read everything

They say you can install Linux on just about any hardware out there. Well, this is certainly out there:

Let's face it: any script kiddie with a pair of pliers can put Red Hat on a Compaq, his mom's toaster, or even the family dog. But nothing earns you geek points like installing Linux on a dead badger. So if you really want to earn your wizard hat, just read the following instructions, and soon your friends will think you're slick as caffeinated soap.

H/T to Scott Raun.

Do Not watch this at work

My thanks to Dick Margulis, who linked to the Impotence of Proofreading.

QotD: Technology

Always be wary of any helpful item that weighs less than its operating manual.

Terry Pratchett

Badly written signs

There's been an amusing discussion on the tech writers' mailing list today about the plethora of badly worded signs. Melissa Nelson posted my top-rated comment so far:

My favorite misleading sign is one they put out in Michigan every summer during construction reminding people that it is against the law to kill construction workers with your car . . . It says "Kill a construction worker $7500 and 15 years in prison." Something about it has a marketing tone and I feel like it is saying "For a mere $7500 and 15 years in prison, you may kill a construction worker." I always get the urge to haggle and see if I can kill two for only $14,000 and 25 years or something. It is very badly written.

Then again . . . my ex was a construction worker . . . so I can never tell if I am just over-editing . . . or if I just need a really good shrink!

Monica hates tech writers

Milan Davidovic sent a link to Monica's declaration of hatred of software tech writers:

10. A last segue, but really important: Your tech writers writing Help files and software manuals. Those guys suck at it. They haven't a clue. They don't know what the hell they're doing. This is not their skill set. When you have to look in five different places to find the answer to how to do one simple process, something's wrong. It's your tech writers. No, I don't care if you've helpfully given another 5-10 links in a Help topic or a reference in a manual to where one can find more information; that's stupid. It should be in the same spot. Computers are supposed to be about efficiency, remember? Instead, use some of those much-vaunted brains and hire some folks who are professionals at writing manuals and textbooks, like college professors who've done similar and so on, and have them write the manuals. People are going to have to buy a book with actual step-by-step lessons, or take a class in how to do things anyway, and you're idiots who are losing a ton of money by thinking tech writing = normal people learning. No. It doesn't. Even for those of us who've read quite a lot of your crap. It's been 30-odd years now. Don't you think it's time you woke up to this little factoid?

She makes some good points, but I wonder if she'd really be happy with her suggested solution: hiring college professors to write software documentation. I've read at least as many badly written college texts as badly written software docs. And the theoretical advantage college profs have over software tech writers is that they're supposed to be experts in the topic they're writing about: most tech writers are not. Tech writers need to interpret whatever information they get from software developers, project managers, quality assurance technicians, and other SME's. Many tech writers think of themselves as "speaker to geeks" within their workplaces.

HTML markup accuracy

Sometimes, it's the little glitches which create the most confusion. Take, for example, this article posted at PC World:

So how big is this IPv6?

Expressed in available addresses, it's so big that only math teachers might care. It is expressed several ways numerically: IPv4, the current one, has about 232 (about 4.3 billion) addresses. In comparison, IPv6 has 2128 (or 3.4 by 1038) addresses or it can be expressed as 340,282,366,920,938,463,463,374,607,431,770,000,000. UNH's InterOperability Lab guru for IPv6, Erica Johnson, said one theory she learned during her research was that Ipv6 has so many addresses that it compares to the number of grains of sand on the Earth. That is certainly more lyrical than the mathematical expression and might actually impress somebody (and is, of course, impossible to disprove). A spokesman at UNH's test lab added that the number of addresses can be expressed as "nearly" 340 undecillion. (Oddly, undecillion is defined as 1 followed by 36 zeros in the U.S., but by 66 zeros in Great Britain, according to Dictionary.com.)

If your eyes normally glaze over as soon as the numbers in the discussion rise above five, the preceding paragraph may not catch your eye as being misleading. Without the careful use of the proper markup (specifically, the superscript <SUP>), you get nonsensical things in your article like "232 (about 4.3 billion) addresses". For most forms of mathematics, 232 does not equal 4.3 billion! 2³² might be a bit closer.

I'm not a mathie, so I'll take their word for it that 2¹²⁸ can be expressed as 340,282,366,920,938,463,463,374,607,431,770,000,000.

Bad UI design

I've encountered some badly designed dialog boxes in my time, but these really must have required a certain special talent in user interface design.

I think this must have been mis-labelled

Here is a list of sure-fire, can't fail, methods for screwing up a project:

[. . .]

3. Set up ongoing committees focusing on management process (such as TQM groups, etc.) and make project team members participate in frequent meetings and write lots of reports . . . preferably when critical project deadlines are coming due.

4. Interrupt team members relentlessly . . . preferably during their time off. Find all sorts of trivial issues that "need to be addressed," then keep their beepers and cell phones ringing and bury them in emails to keep them off balance.

5. Create a culture in which project managers are expected to "roll over" and take it when substantive new deliverables are added halfway through the project. (After all, only a tradesperson like a plumber or electrician would demand more money or more time for additional services; our people are "professionals" and should be prepared to be "flexible.")

[. . .]

Several high-tech firms I've worked for clearly had the entire list down cold . . . but it had been accidentally mis-labelled as "Project Management Bible". That's the only way I can account for the number of companies in the field who do all the things listed in the checklist deliberately.

Hat tip to Rick Bishop, who sent this link to the Tech Writing mailing list.

QotD: Novelists

Every writer of note, when I've scratched the surface, turns out to come from a lively context of other writers, correspondents, editors, critics, and literate and argumentative friends and colleagues. This observation has given me my personal definition of a genre — "Any group of works in close conversation with each other." As readers, we tend to encounter only the polished result of that uproar, as the book alone appears in our hand and the context drops away. I'm not sure this is a bad thing — like law and sausages, it may sometimes be better not to watch how novels are made.

Lois McMaster Bujold, "How I Met the Inklings", 2006-08-06

Spelin' gud in Po't Hohp

This one was so bad, I had to stop and snap a quick picture . . . but you'll have to visit The Back Seat Grammarian to see the true horror of home-cooked spelling.

This was on the main street in Port Hope on Saturday.

Words as blunt instruments

Okay, it's only the runner-up this year, but I thought it was brilliant:

"I know what you're thinking, punk," hissed Wordy Harry to his new editor, "you're thinking, 'Did he use six superfluous adjectives or only five?' — and to tell the truth, I forgot myself in all this excitement; but being as this is English, the most powerful language in the world, whose subtle nuances will blow your head clean off, you've got to ask yourself one question: 'Do I feel loquacious?' — well do you, punk?"

Stuart Vasepuru
Edinburgh, Scotland

Go read the rest of the entries. Hat tip to Ron Hearn, who sent the link to the Techwr-l mailing list.

O pleez spehr mi!

Yet another bone-headed attempt to "simplify" the language (as if l33t-speak hadn't already become the online world's lingua franca):

When "say," "they" and "weigh" rhyme, but "bomb," "comb" and "tomb" don't, wuudn't it maek mor sens to spel wurdz the wae thae sound?

Those in favor of simplified spelling say children would learn faster and illiteracy rates would drop. Opponents say a new system would make spelling even more confusing.

Eether wae, the consept has yet to capcher th publix imajinaeshun.

The funniest part of the article is this claim:

Thae sae th bee selebraets th ability of a fue stoodents to master a dificult sistem that stumps meny utherz hoo cuud do just as wel if speling were simpler.

Yep. Making a system simpler would make mastering that system easier. Except for those of us who already use the older, more complex system. I don't know about any of you, but I find my reading comprehension drops to a crawl when I try to parse those "simplified" sentences in the quoted text above. And worse, the "voice" I hear the words in is pretty stereotypically rural — slow, oddly paced, and with terribly unsophisticated pronunciation.

QotD: Speaking and Writing

As it happens, I'm reading Volume I of the collected Orwell, and the comparison between his prose and mine is the occasion for much pained wincing. But at least when I use a long word, it's not because I think I'm getting paid by the syllable (in acclamation). No, actually, this is the way I talk. Disturbing, I know. If you've ever wondered what it would be like to live with a character from a slightly stilted Edwardian novel--well, just ask any of my roommates. Except I can't do all those complicated hairstyles or twirl a parasol.

But I digress. To my mind, the very best prose is the kind where you can't quite put your finger on why it is so damn good . . . where the whole thing is so polished, precise, and true that you can't pick out a single, clever sentence to put in your quote diary. Sadly, I'll never have the pleasure of producing such . . . but I can admire it in others.

Jane Galt, "Crossed Signals", Asymmetrical Information, 2006-05-10

QotD: Bad Wine Reviews

While reading Parker can help increase your knowledge about wine, reading bad wine writing doesn't teach you much. Here's Robert Draper in the February 2002 issue of GQ, writing about the 1999 Bacio Divino: "The '99's fruit attack soars like a meteor shower, then seethes in the palate like a cosmic bath of nearly unplumable depths . . . like an unforgettable encounter with a raven-haired ingenue, one is left feeling exhilarated, intrigued, and ultimately covetous." Pfui! That's purple prose all right, and not because it's stained with wine. Besides saying nothing, the paragraph ought to be used in writing schools as an example of mistakes to avoid. Meteor showers don't soar, they fall to earth. Things may seethe on the palate, but not in the palate. The word is unplumbable, not unplumable. And while I may have been exhilarated and intrigued by my encounters with raven-haired ingenues, I've never been covetous. But I thank Mr. Draper for such a magnificent example of bad writing.

Jeff Cox, Cellaring Wine, 2003

A tech writer's blog

Dick Margulis, one of the regular participants on the TECHWR-L mailing list, has started his own blog, which he's chosen to title in this manner:

words / myth / ampers & virgule

occasional essays on working with words and pictures
—writing, editing, typographic design, web design, and publishing—
from the perspective of a guy who has been putting squiggly marks on paper for
over four decades and on the computer monitor for over two decades

And, no, don't panic: it's not just about the persnickety details of technical writing . . . if it was, even I wouldn't go there!

QotD: Syntax

It is syntax that gives words the power to relate to each other in a sequence, to create rhythms and emphasis, to carry meaning — of whatever kind — as well as glow individually in just the right stuff

Virginia Tufte, quoted by Virginia Postrel in "Artful Sentences", Dynamist Blog, 2006-04-06

Brief snapshot of my trip

On the way from the airport to the off-site meeting Jon and I were attending, we stopped to blow off some steam:

Our local co-worker who took the photo then distributed this image as a "Wanted" poster to the rest of our meeting attendees.

Do I need to say that the meeting went very well?

Writers and editors

This article was forwarded to a tech writing mailing list, where our professional experiences are remarkably close to those of our reporting kin:

We writers, while getting the credit on the page, have to deal with a group of folks called editors. Editors are the threshold guardians of the printed word. Their job is to take a writer's vision and bluntly tell him that it's not clear and that he must state it in half the space.

(Ed. note: be careful, laptop jockey, this piece could be dropped...)

Editors are the heroes of the printed word, the kings of the First Amendment.

(Ed. note: well . . . a bit flashy but we don't want to get in the writer's way. keep this line.)

They can also be impossible, short sighted, and cruel . . .

(Ed. note: three of us think these are still compliments, two are unsure.)

. . . And, of course, clueless.

(Ed. note: it's almost unanimous that this is NOT the compliment section.)

Many times a writer looks at his finished work with sadness. He thinks of how much better it could have been had he been allowed to keep certain lofty and majestic lines.

(Ed. note: you mean the lines we put up on the dartboard at the office?)

Of course, I don't think this way about my own editor. Hi Anne!

Hat tip to Bonnie Granat.

A valuable online resource . . .

. . . except that the very people who most need the help are the ones least likely to use it.

Hat tip to "JtMc".

Creative Writing

I've often said to people who want to be creative writers that the worst possible job for them would be to go into technical writing. A good technical writer is always concerned with writing too much . . . a good creative writer is most often concerned with writing too little. These folks should probably consider careers that do not involve creative writing. Or any kind of writing.

Hat tip to Greg Slade.

It's remedial spelling time, kids!

I'm ashamed to admit that I'd never visited the notorious "MY Vast Right Wing Conspiracy" before today. I guess I was expecting something a bit less coherent and rather more ranting than what I found. Almost the first thing I read was directly in line with my thoughts on a pet peeve: atrocities in English on the web:

Time for another English lesson

Dammit, internet. Now I’ve got to break out the bullwhip AGAIN.

Bulwer-Lytton remembered

It's not technical writing, although much so-called technical writing might qualify:

A man who compared a woman's anatomy to a carburetor won an annual contest that celebrates the worst writing in the English language.

Dan McKay, a computer analyst at Microsoft Great Plains, N.D., bested thousands of entrants from the North Pole to Manchester, England to triumph Wednesday in San Jose State University's annual Fiction Contest.

"As he stared at her ample bosom, he daydreamed of the dual Stromberg carburetors in his vintage Triumph Spitfire," he wrote, comparing a woman's breasts to "small knurled caps of the oil dampeners."

The competition highlights literary achievements of the most dubious sort - terrifyingly bad sentences that take their inspiration from minor writer Edward George Earl Bulwer-Lytton, whose 1830 novel Paul Clifford began, "It was a dark and stormy night."

Punctuation is very important

John Turner sent me this link a long, long time ago. For some reason (me being deathly ill with the flu, if I remember correctly), I never checked out the link. Until now. Now I must insist that you also find out the secrets of email punctuation. You'll need to listen very carefully to the presentation.

SGML tagging is bad for your mental health

A co-worker of mine finally snapped over an exchange with an SGML/XML advocate, and sent this email to our boss:

In other news...

<total_disbelief>I just re-read [SGMLguy's] e-mail where he talks about <he's_got_to_be_kidding>SGML</he's_got_to_be_kidding> and <no_way>tagging everything manually by hand</no_way>.</total_disbelief>

<query>He is kidding, right?</query>

<I_mean,_come_on,_work_with_me_here>It would take absolutely <emphasis>forever</emphasis> to write something the length of, <for_example>[one of our book titles]</for_example>, if you had to <bloody>tag</bloody> everything by hand. And what happens when a writer forgets to <it_blows_up_real_good>close a tag?</it_blows_up_real_good></I_mean,_come_on,_work_with_me_here>

Oh well. I should not let it bother me.

Too much

QotD: Writers and Writing

A scrupulous writer, in every sentence that he writes, will ask himself at least four questions, thus: What am I trying to say? What words will express it? What image or idiom will make it clearer? Is this image fresh enough to have an effect? And he will probably ask himself two more: Could I put it more shortly? Have I said anything that is avoidably ugly? But you are not obliged to go to all this trouble. You can shirk it by simply throwing your mind open and letting the ready-made phrases come crowding in. They will construct your sentences for you — even think your thoughts for you, to a certain extent — and at need they will perform the important service of partially concealing your meaning even from yourself.

George Orwell, "Politics and the English Language", 1946

Fear and Loathing in TechWriterWorld

The current disaster agitating the collective Chicken Littles of the technical writing world is the purchase of Macromedia by Adobe. Many feathers are being ruffled, and much running-in-circles is being accomplished.

Scott Adams, the creator of the Dilbert comics, once joined the big technical writing mailing list under a pseudonym. He left the list after a couple of weeks and added new character called "Tina the Brittle Tech Writer" to the Dilbert world. The denizens of the list were outraged, and much fuming and snarking ensued . . . proving that Adams had absolutely nailed the character of Tina.

These days, when someone asks me what I do for a living, I tend to evade the question a bit. "Oh, I work in software." If pressed, I'll name my employer, but it takes a persistent questioner to get me to admit to being a tech writer.

Tech writing. It's not what I am, it's just what I do. [Hangs head in shame.]

Update: In counterpoint to the unsteady manic-depression cycle of tech writing (or insurance sales: see comments), I offer the uplifting tale of training budgets, BOFH style.

Meetings, bloody meetings

Last night, under some persuasion, I attended a meeting of the local STC chapter to listen to Chris Greaves talk about business communications. I've known Chris for more than 20 years, but we'd lost touch and I hadn't actually seen him in over 14 years.

The meeting was quite well-attended, and I encountered a few friends and acquaintances from jobs past (in some cases long, long past). Chris himself was in fine form, loosening up the room with some corny jokes (at least, most of the attendees would have assumed Chris was joking . . . I suspect he did nothing more than tell the truth in an amusing fashion). He emphasized getting to the essence of business communications: it's not business communication unless you are exchanging paper — and one of those pieces of paper has to be a cheque.

Chris also provided some advice for people submitting business proposals and people writing resumés: tailor the document to the specification. In the case of a business proposal, ensure that you address all of the requirements. In the case of a resumé, re-iterate all of the skills requested in the job ad. Both types of document have the same basic goal: to get you in the door for an interview. The way to maximize your chances of doing that is to ensure that your document/resumé matches what they think they're looking for.

He also discussed the importance of focussed business cards: most business cards contain too much clutter. He's against the use of logos, generic graphics, ideograms, cartoons, and other such non-text elements. His belief is that the essential purpose of a business card is to convince someone to call you: the single telephone number is critical. It's so critical that on one of his own business cards, all that appears is his phone number — in 48-point bold type, front and back.

I'd tell you more, but Chris would probably have me bumped off if I spilled too much of his sooper-secret-skillz here.

After the meeting, Jon and I had coffee with Rob Hanna, who is suffering from the technical writing world's greatest affliction: the urge to create a Universal Information Model (it's our equivalent of the fiction writers' "Great American Novel" syndrome). I enjoyed listening to his basic overview, and I think he'll be well received at the conference he's going to be presenting at later this year. The problem, as always, with UIM's is that they need to be implemented by mere humans with agendas of their own. I encouraged Rob to find ways to make his model more palatable to those who will be most likely to fight against any sort of changes to their jobs. If he can do that, he's at least got a shot at some success, if not quite fame and fortune.

Update: I forgot to mention the most poignant part of the evening: when a frickin' speechwriter from the Liberal Party of Canada started working the room in hopes of drumming up some non-political work. He was peppering his routine with disarming comments like "we're all on the way out now".

The Tech Writing World is Aghast!

Adobe has announced that they'll be outsourcing development of their FrameMaker product line to Microsoft:

Adobe Systems Incorporated (Nasdaq:ADBE) today reported strong interest by Microsoft (Nasdaq: MSFT) in Adobe FrameMaker technology co-development.

Microsoft has said that the boom in XML development and publishing has left them in need of strong partnerships with companies that are leading the XML publishing market. To that end, discussions between both companies have led to a working agreement to co-develop a future release of Adobe FrameMaker.

"We had been seriously considering the discontinuation of the entire FrameMaker product," said Bruce R. Chizen, chief executive officer. "However, with the interest of a partner such as Microsoft to assist in the development costs and to help in the marketing and distribution through a variety of resellers, we re-evaluated our position. I'm very happy indeed to be able to state that we are going to continue the development after all."

Further in the press release, they point out the key part of the deal:

While Microsoft continues to be the most powerful company in the software market, most people agree that Adobe has shinier, and prettier marketing pamphlets.

Adobe therefore will develop and distribute the bulk of the marketing materials for FrameMaker. By continuing to use the same fonts, graphics and page size Adobe is showing a committment to the products longevity. Says Chizen, "make no mistake about this. We know that our glossy paper and great font faces, such as Minion and Myriad, continue to impress people who look for software. We plan to distribute marketing materials across the country and around the globe."

The Curse of Docco

"I had just started to open FrameMaker when the drugs began to take hold. . ."

So starts the unpublished tale of Gonzo technical writing by the late Hunter S. Thompson, who apparently tried turning his attention to software documentation during the early 1990's. The hand-written story was found in the bottom of a case of shotgun shells that appeared on the desk of the CIO of [name removed for legal reasons], a medium-sized software company in Silicon Valley. Only a few barely legible pages survive — or perhaps are the only parts Thompson ever set down during his life.

I love stress myself, and I have learned to survive under savage and unnatural pressures. I am a stress freak. On some days it seems like I have lived in my cubicle for half my life. There is blood in this keyboard, and some of it is mine. You don't need to be paranoid in the savage, world of software: it makes you paranoid. The wolves are always there, waiting for that split-second of inattention to hurl themselves upon you and rip off steaming chunks of your flesh. I survived this hell, but only through judicious applications of drugs, alcohol, and carefully placed .45 caliber bullets. [. . .] The department manager was Bruce Hawkins, an Australian, and a true drunken bastard in the classic mold. He always referred to the department as "Docco". I hated that, but the man had a survival instinct. No matter how often we tried to get rid of him, he'd be back the next day, blood in his eye and beer on his breath. I still don't know how he survived the time I cut his brakeline (the office was at the highest point of the hill, with a long twisting road down to town). The skin-flayer of the week was the status meeting, where the tortured souls of the department were taken out for beatings and repeated humiliations. With the right mix of ether and peyote, I could survive the worst the manager had to offer. The screams I could suppress, until the hyenas started to howl, just as the [illegible] tore open and the bile spewed out. Your everyday Nervous Breakdown is nothing compared to the hopeless Craziness of a woman who woke up a team lead on the flagship product and went to bed as the new trainer for interns. This is a guaranteed overwhelming shock to the system; if you don't go insane from suddenly having to see the world from the POV of the brain-dead new intern, your mind will be churned into butter by having to crawl, head-first, with your eyes open, down a septic tank hatch, just to have a place to sleep. [ . . . ] Programmers are swine. They know it. They go out of their way to prove it. But I know how to treat 'em. You need to cut out the head swine from the herd and break him; that forces all the others to give you respect, and tell you when they fuck with your software. I favour cutting off the little toe on each foot: no head swine can keep the respect of his homies when he's unable to walk in a straight line, bouncing off partition walls and filing cabinets, wailing his distress. [ . . . ] I have always hated editors, and I like to have sport with them. They are harmless quacks in the main, but some of them get ambitious and turn predatory, especially in Silicon Valley. In Santa Cruz, I ran into a man who claimed to be Microsoft's chief editor. "I consult with Bill Gates constantly," he told me. He produced a business card and gave it to me. "I can do things for you," he said. "I am a player." I took his card and examined it carefully for a moment, as if I couldn't quite read the small print. But I knew he was lying, so I leaned toward him and slapped him sharply in the nuts. Not hard, but very quickly, using the back of my hand and my fingers like a bullwhip, yet very discreetly. He let out a hiss and went limp, unable to speak or breathe. I smiled casually and kept on talking to him as if nothing had happened. "You filthy little creep," I said to him. "I am Bill Gates!" That was the tone of my workdays in Silicon Valley: violence, joy, and constant Mexican music. [ . . . ] The one I knew I had to keep my eye on was the office intern, a pimple-faced whelp whose reptilian gaze and inability to sweat marked him as potentially deadly. I pistol-whipped him on his second day, just to keep him off-guard. His life revolved around TV and relentless masturbation. Deprive him of one and he collapsed. That was the key; showing him that you had to power to destroy him. Vaya con dios, amigo. I consider myself a road man for the lords of karma. [. . .] Why bother with technical writing, if this is all they offer? Hawkins was right. The writers are a gang of cruel faggots. Technical writing is not a profession or a trade. It is a cheap catch-all for fuckoffs and misfits — a false doorway to the basement of life, a filthy piss-ridden little hole nailed off by the building inspector, but just deep enough for a wino to curl up from the sidewalk and wank off like a monkey in a zoo cage.

 

 

 

 

 

 

 

 

 

 

 

 

 

The preceding post is complete fiction, derived in very large part from the works of the late Hunter S. Thompson. Don't sue me!

Watch Your Language

Geoff Hart posted this to the Tech Writing mailing list earlier this week (and reproduced here with his kind permission):

From the March 2005 Consumer Reports, which displayed a photo of the French text on the "care" label attached to a handbag produced by the Tom Bihn company in the U.S.:

[English label not shown but described by CR]: Hand-wash in warm water with gentle soap, and hang to dry. Do not use bleach. Do not machine-dry.

French: Laver à la main à l'eau tiède, savon doux, étendre pour secher. Ne pas javelliser. Ne pas secher à la machine. Nous sommes désolés que notre président soit un idiot. Nous n'avons pas voté pour lui.

For those whose French is of the "plume de ma tante" variety, the extra French text says: "We're sorry that our president is an idiot. We didn't vote for him."

Please let's not turn this into a political discussion. The lesson for those of us who do or review translation is that someone needs to check the translations carefully. In this case, the extra French seems to have been an intentional political comment by the manufacturer, but I've seen similarly egregious errors that crept in when nobody did the QA.

Geoff also pointed out that the company itself recognized the, um, interest this little item would provoke.

QotD: Writing as a Career

Leftist writers raised in affluent circumstances — as I think even they would admit, in honest moments — suffer from heroic self-image as an occupational disease. And perhaps this is equally true of the conservatives as well. But when you come from the actual working class — when your father is someone who actually helps assemble buildings, as opposed to designing them — you can never, as a professional intellectual, shake the suspicion that you are going to get caught and sent back to [earn] a proper living. I think it's part of why relatively minor career crises have such a shattering effect on my nerves; as a columnist I've turned out to be much more of a cowardly beggar for editorial reassurance than I ever thought I'd be. It's because I see my career subconsciously, and always will, as the product of some inchoate power's inexplicable carelessness.

Colby Cosh "Who let him in?", ColbyCosh.com, 2005-01-19

When Clear Writing Loses Out to Weird Jury Decisions

This link was posted to a tech writing mailing list I lurk on: Toilet Brush Warning Wins Consumer Award:

DETROIT - The sign on the toilet brush says it best: "Do not use for personal hygiene."

That admonition was the winner of an anti-lawsuit group's contest for the wackiest consumer warning label of the year.

The sponsor, Michigan Lawsuit Abuse Watch, says the goal is "to reveal how lawsuits, and concern about lawsuits, have created a need for common sense warnings on products."

The $500 first prize went to Ed Gyetvai, of Oldcastle, Ontario, who submitted the toilet-brush label. A $250 second prize went to Matt Johnson, of Naperville, Ill., for a label on a children's scooter that said, "This product moves when used."

Further comments, I'm sure, would only add to the mountain of evidence that juries in certain jurisdictions are packed with the only people who couldn't come up with a way to convince the judge to let them escape jury duty. And that most judges would consider an IQ above room temperature to be adequate reason.

Technical Illustration

Brian Micklethwait discusses a new concept in digital cameras, which could be very useful indeed for anyone trying to write instructions for physical devices:

Think of all those instructions manuals where, in order to explain things properly, they cannot use photos, because photos are not clear enough, and must instead resort to laboriously created line drawings. Well, this gadget creates line drawings like that automatically.

Multi-flash imaging promises to facilitate and pioneer complicated rendering of mechanical objects, plants, or internal anatomical parts. Because of its ability to detect depth discontinuities, it may render shapes that would otherwise be difficult to perceive. For instance, a car engine could easily be captured in a non-photorealistic image and then superimposed over an actual photograph of the engine resulting in a superior manual illustration (see example below). Alternatively, a skeleton with complex network of white bones could be efficiently reproduced for instructional medical visualization. Additionally, an endoscopic camera enhanced with the multi-flash technology promises to enhance internal anatomical visualization for researchers and medical doctors.

I wonder if the kind of cheap digital cameras you can now buy for $200 will soon have this kind of facility.

Most of my technical writing has been about software, so this device wouldn't be as immediately useful to me as to someone in other industries — but it's a really cool idea.

Yet another "End of the World" story

Reuters reports the death of the English language. Again.

The English language is being destroyed by a "deadly virus of management speak" which has infected the mouths and minds of politicians like Tony Blair and George W. Bush, a leading UK journalist said Monday.

The British Prime Minister and his ally the U.S. President are mangling the language, destroying its meaning by avoiding the use of verbs, twisting nouns into verbs, and endlessly repeating phrases until they become "zombified."

"It's deeply depressing," says John Humphrys, one of Britain's leading political journalists and the author of a new book, "Lost for Words," about the demise of the language.

Humphys' book laments the growth of "cliched, dumbed-down, inflated and bogus management-speak" which he says now passes for English.

This one strikes close to home

Charles Stone, Jr. writes about the developing "right" not to be offended:

Every time you turn around today you are almost sure to offend someone. In our land of victimhood it has become difficult to avoid saying or doing something which will cause someone else to feel bad or put upon or irritated.

One of the great strengths of the Inquisition was that they had the power to arrest you, question you, torture you, but they had no corresponding obligation to inform you of what charges you were being prosecuted for or what suspicions they might be entertaining about you. You were expected to confess to all your sins. The Inquisition often found that their victims would confess to just about anything in order to end the inquiry.

Tech Writing and Constitutions

Lady Liberty tries to assemble something from the instructions:

If you've ever bought toys for a kid or some of that inexpensive pressed-wood furniture, you know exactly what the problem is with "some assembly required" goods. It's not that it's safer to ship delicate parts and pieces unassembled in in their own protective styrofoam cocoons. It's not that bookshelves take up far less room in the box when the component boards can all lay flat against one another. No, the problem typically lies with the instructions intended to help you through that "some assembly" that's required of you.

I'm not a stupid woman. I can handle simple tools such as hammers and screwdrivers with ease. I think I speak and understand the English language with some fluency. But when I see a sheet of instructions flutter out of a box of whatever it is I've purchased, I positively cringe. In far too many of my own experiences, the instructions appear to be put together by someone for whom English is not a first language and not a particularly fluent second language, either. And the translations all too often strike me as having been written by engineers in the first place. In other words, they're hopelessly — needlessly! — complicated, and the confusion is only multiplied when there's some question as to the sensibility of the words themselves.

I'm sure almost all of us have had similar experiences! In fact, some of us even cause 'em

Back at the office, I stared at an instruction sheet the manufacturer had kindly blown up to poster size. I caught glimpses of "insert anchor post (part 19) firm into base taking care to be frontward facing (part 2) until snap together is solid (caution to be careful post does not break)" and "refer fig. 17a on reverse" and I shuddered. Why does something that could be so simple have to be made so needlessly complex? Hours could be saved; frustration could be minimized. And if the instructions were simple and easily understood, the product would almost certainly work as advertised the first time you finish building it.

It wouldn't surprise me in the least that many of these assembly instructions are written by exactly the same kind of people who author legislation or government regulations. By trying to address specifically every possible contingency, the verbiage is almost always overly complex. Debate and compromise doesn't lead to consensus but rather to added layers of nuance (. . .not permitted under statute except when capitulated under conditions as described in part 17, paragraph 4 and within the parameters further defined under the itemizations of attachment D which is in effect for the first 120 days of the transition to . . .)

Sometimes, it's just bad writing. Sometimes it's written that way because the company is trying to cover off all sorts of issues in the shortest possible way. Sometimes, they're trying desperately to hide something (like the product not actually working the way it's supposed to).

Andrew Plato's "Ten Rules of Technical Writing"

Andrew Plato is perhaps the funniest technical writer in captivity: that's partly because he's no longer doing a lot of technical writing (I've been told that the sense of humour grows back after a while). Here are a pair of Top Ten lists he wrote for the Tech Writer's mailing list. First, the "serious" one.

To be a good tech writer:

1. You understand or are willing to learn the subject matter.
2. You have no emotional attachments to your work. You see it as product that needs to be perfected, not an expression of yourself.
3. You ask relevant, probing questions and listen to the answers.
4. Prioritize your time. Focus on what is most important: content.
5. Answer the 5 Golden Questions:
1. What is it?
2. What does it do?
3. What is its purpose?
4. How does it work (or how does it do what it is supposed to do)?
5. Why is it relevant?
6. Master your environment and information. If you act like a cog in a machine, you will be treated and respected accordingly. Take control of the process. Use it to your advantage.
7. Demonstrate your expertise. Prove your knowledge.
8. Good writing is 5-10% fonts, styles, and grammar and 90-95% brain-numbing, keyboard-pecking, intellectually draining drudgery. If this ratio tilts too high to the fonts and styles side, you're probably not focusing on the right things.
9. Results are more important than plans.
10. Criticize things you don't know about. Live in a swamp and be three dimensional. Get all excited and go to a yawning festival. Go into a closet and suck eggs.

Apparently near the end of the list, he stopped prescribing what should be the tech writer Zen ideal and started talking about how real tech writers work. . .

The "real" list is more descriptive than prescriptive. This list was inspired by a long, long, long, tedious, long, long, boring, long, long discussion on the Tech Writers mailing list which devolved into a mud-slinging contest between the pro-STC and anti-STC factions:

10. Develop a style guide. First thing make sure you get every possible style perturbation figured out. This is very important.

9. Write a comprehensive documentation plan. Don't skimp here. You need to plan out every last detail of your documents. I usually allow 5 to 10 days to design and write the plan. Make sure you follow all your styles.

8. Single-source everything. There is simply no excuse for not using the latest single-sourcing systems. These can dramatically cut down on writing time and really make you more productive.

7. Hold weekly meetings, with everybody. Use this time to express your issues about management, projects, and levels of respect. Break out into cross-functional teams to form consensus on how to more effectively leverage your team synergies.

6. Get specs. Don't even think of starting work without detailed specifications on exactly what you should be doing.

5. Set expectations. Require detailed written expectations from management. Point out any deviation from these expectations.

4. Join the National Writers Union: This is the best place for fellow writers to get together and talk about employment issues. And when you get into trouble, the NWU can lend a hand and help you suck the life our of your employer.

3. Get the best tools: Make sure you spend ample time evaluating, cross-evaluation, and double-crossed evaluating tools and technologies. No plug-in or code snippet it too small. Document your evaluations and distribute these via executable files to everybody in your organization.

2. Remain Writer-focused: Don't let your company encourage you to learn about technologies. Remember, a good writer can document anything without knowing about it. Use your SMEs wisely and make sure you focus on what is important: fonts, styles, and communication.

1. Join STC: Devote yourself to this outstanding organization. The services it offers technical writers is truly remarkable. From seminars to lunch-and-learns, there is virtually no end to the valuable resources STC offers technical communicators. Make sure you also only work with those people that are also STC members!

Why Technical Writing Matters

This article in The Grauniad talks about some Microsoft blunders in internationalization, or as we not-so-fondly call it "I18N".

You can be certain that Microsoft is not the only software company guilty of this sort of sin.

Tech Writing Geek Alert: Style Guide Hatchet Job

Andrew Plato is a former technical writer who has unique insight into the quirks and weirdnesses of the profession. This is a posting he made today to Techwr-L, a mailing list for tech writers:

Developing a detailed, barely-used style guide for your company: 100 hours

Obsessing over minor editing nits: 200 hours

Trivializing content so you can play with the latest features in FrameMaker: 50 hours

Flummoxed at why nobody respects you at work: priceless.

For all those times you need it: Font Fondling. It's wherever you are.

PS: Get the hell back to work, you!

XML Considered Harmful: Film at Eleven

A real world view of playing with fire, uh, I mean XML. If those three letters mean nothing to you, the article would also be less than illuminating.