A Techie Tech Writer Blog

My gloss on this picture: If you're confused, go back to the IKEA store and borrow their phone with a really long extension cord, so you can call support from the parking lot.

Last weekend, my husband and I helped a couple of friends, Amanda and Stephen, move into their first owned home. They took the occasion of this move to upgrade and expand their furniture collection with several new items from IKEA. And they hired a service to assemble the furniture. I hadn't realized that such services existed. I'll have to keep that in mind as an alternative career if I get burned out on this tech writing thing. I'm blessed with the right combination of visual, spatial, and motor abilities such that I actually enjoy assembling IKEA furniture. Not everyone is so fortunate (if you want to call it that). As Stephen said, "If I had to do all this, the result would be divorce and me burning the house down." As it happened, a miscommunication meant that the service didn't have time to assemble all the items, so I got to do a couple of them after all.

IKEA is known for keeping their prices as low as possible, and one of the ways they do that is with almost completely wordless pictorial instructions. The fewer words they use, the fewer words they have to pay to translate. The instructions for a bookshelf I recently assembled for myself included a single note that was translated into 18 languages, and therefore took up about half a page. Minimizing text also reduces page count and printing costs. Another way that IKEA reduces printing costs is by using newsprint-quality paper for the instructions in some (but not all) products. Unfortunately, this means that the print quality is also low, and fine details can be difficult to discern for all but the sharpest eyes. Figuring out how pieces fit together can depend on matching the positions of tiny dots in the diagram to those of holes in the physical pieces, so fine details matter a lot.

Wordless instructions may transcend language, but that does not mean that they are universally usable. Some people are just not visual learners. Amanda said, "I can't make sense of those diagrams, but I can do it when Janet explains it." She's more comfortable with verbal instructions than visual ones. In other cases, physical limitations are the issue rather than cognitive style. Stephen is an awesome photographer; he's also visually impaired, so those tiny dots on newsprint are a non-starter. The same can be true for those of us who find our arms getting shorter as we get older and our near-distance vision degrades.

No doubt IKEA has carefully weighed the costs and benefits, and determined that wordless instructions make the best sense for their business. Wordless instructions are sufficient for the majority of their customers, and many of the rest can be helped by phone support. They leave open a market opportunity for furniture assembly services, and IKEA doesn't mind ceding the space, as long as they still sell bookshelves. I wonder if there's also a tiny market niche for verbal instructions to go along with the pictorial ones.

Just as every industry and domain has specialized jargon, so too do organizations have unique terms for things, activities, and people. Here are some of the terms I'm encountering at Mozilla. This doesn't mean that they're unique to Mozilla, just that I haven't heard them before (or in the case of "awesome", nearly as much).

Chemspill

An emergency release of software, in response to a potentially negative event. This was originally coined with reference to security vulnerabilities, particularly when the hole is actively being exploited by bad guys. However, just recently, Firefox 3.6.6 was released as a chemspill to fix a poor choice for a default setting. This release came quick on the heels of Firefox 3.6.4, which introduced a feature to detect when a plug-in (such as the Flash player) is hanging. In 3.6.4, the default time to trigger this feature was set at 10 seconds, which was too short for many older computers, causing problems for a great many users who upgraded. Hence, a chemspill release of 3.6.6 was done in record time, to change the default to 45 seconds. (The value is configurable, but most users don't know (and shouldn't need to know) how to change it.)

Landing

When a code change is checked into the main trunk of the source control system, it is said to have "landed". I like the imagery of code as birds circling and descending to alight on the (code) tree.

Awesome

This word has the same basic meaning as in common, informal American English, but it's used much more frequently and enthusiastically within Mozilla culture than in the general population. It can range from indicating mild approval to expressing the highest praise, but tends to cluster on the upper end of that scale. Its use is almost always sincere and non-ironic, though it may carry a tinge of self-consciousness. In addition to its usual role as an adjective, "awesome" can also function as a mass noun as in "too much awesome" or "army of awesome". When the Firefox location bar (where you type URLs) was enhanced to support keyword searching and autocompletion based on history and bookmarking, the enhanced functionality was dubbed "the Awesome Bar" by developers, much to the consternation of localizers.

One term of art in technical communication that just bugs me is "content". It's the term we use to describe information when we don't want to be specific about the format (text, graphics, audio, video).

The Free Software Foundation has an interesting take on this term:

... using the word ["content"] as a noun to describe written and other works of authorship ... regards these works as a commodity whose purpose is to fill a box and make money. In effect, it disparages the works themselves. ...

The term “content management” takes the prize for vacuity. “Content” means “some sort of information,” and “management” in this context means “doing something with it.” So a “content management system” is a system for doing something to some sort of information. Nearly all programs fit that description.

My objection is more on the intellectual side. "Content" is just so vague that it could mean almost anything. It implies "stuff that goes inside something else", which could include, say, peanut butter. I think the term "content" has gained currency thanks to web designers, whose primary concern is the form of a design, with the content that goes into the form being somebody else's concern. But for those of us who provide it, the fact that content fits into a form is a secondary feature.

Unfortunately, none of the alternatives is much better. "Information" and "communication" are nearly as broad. "Knowledge" is also broad, and not all content rises to the level of knowledge in the DIKW hierarchy of "goods of the mind". I mention this merely as an excuse to quote T.S. Eliot's The Rock:

Where is the Life we have lost in living?

Where is the wisdom we have lost in knowledge?

Where is the knowledge we have lost in information?

The best alternative to "content" that I can come up with is the slightly longer phrase "content assets". While this still relegates works of authorship to the status of a commodity, it at least makes the concept into a count noun instead of a mass noun, and implies that the commodity has some intrinsic value beyond filling a box.

I realize that "content" is already so prevalent that it's not going to be changed any time soon. But I still can indulge in an inward cringe when I read or hear bare-bones "content", and engage in a private crusade to use "content assets" instead.

XCKD addresses an important punctuation question that I've wrestled with in e-mails and other online writing:


I usually use the first option, despite the imbalance:
... linux (or bsd :-) ...

However, this looks especially imbalanced when the renderer (e.g., e-mail program) displays well-known smileys as little icons:
... linux (or bsd ...

The second option solves the latter problem, but in plain text it looks too much like a double chin to me:
... linux (or bsd :-)) ...

A solution to the balance issue would be to use a reverse smiley to introduce the parenthetic content:
... linux (-: or bsd :-) ...
However, this solution fails in the case of smiley-rendering, because such programs usually don't recognize reverse smileys. It also implicitly requires that the entire parenthetical content be humorous, whereas in some cases only the last little bit is actually humorous.

Another option is to insert a space to create visual distance between the smiley and the closing parenthesis, so that the smiley is now more clearly just part of the parenthetical content:
... linux (or bsd :-) ) ...
This preserves balance while surviving rendering. Multiple spaces may be necessary to create adequate separation.

What other solutions have I missed?

Update: I forgot about Japanese-style emoticons, which don't require turning your head, and which usually involve balanced sets of parentheses:
... linux (or bsd (^-^) ) ...
In this case, the right-paren of the emoticon really can't do double duty as the closing paren of the phrase, and a space really does seem necessary. This becomes even more apparent in versions that include forward- and back-slashes:
...linux (or bsd \(^-^)/ ) ...
See Hiroette.com for a menagerie of Japanese smileys.

Yelling and throwing things.

These may be behaviors of cranky preschoolers and temperamental Hollywood divas. They are also reactions of readers to bad documentation, according to a survey conducted by "The TechGuys", a UK-based technology support provider, and reported by Channel 4.

The TechGuys survey of more than 1,500 consumers revealed that nearly 40% of the respondents became so irate that they yelled with frustration due to the over-complicated nature of instructions. And one in five even threw the offending manual across the room.

Linguist David Crystal, who was quoted in the Channel 4 report, elaborated on the problems that lead to "read rage" in his own blog post on the subject. These are likely to be familiar to professional tech writers. These are the demons we battle daily:

• thick manuals with only a few pages in English
• one manual covering multiple models, making it difficult to find relevant information
• manuals only available online, when the product itself must work in order to get online
• small print in general and illegible labels in diagrams
• online documents with dense paragraphs and poor page navigation
• manuals written by non-native English speakers, and never edited by native speakers
• long complex sentences
• poorly ordered procedures
• missing explanations, such as for product variations, or product handling
• instructions that are culturally inappropriate or just plain nonsensical

The job of technical writers is to produce information that is easy to use, easy to understand, and easy to find. If our employers don't provide us with the resources to do our jobs, then our jobs become to obtain those resources. I don't recommend yelling and throwing things as a persuasive strategy, but if your customers are doing it, maybe management needs to see that.

Cherryleaf is running a quick poll on the question:

Would you feel happy allowing readers to remix your manuals?

(They use a snazzy poll widget from xat.com.)

The concept of content remixing is entering the mainstream of the tech writing world, thanks in large part to attention from Scott Abel at The Content Wrangler paid to FLOSS Manuals and its support for remixing. A month ago, would most tech writers have understood the question?

If we're talking about manuals that I write, I think the question should not be "Would I feel happy" about it, but "Would my users do it and find it useful?". My feelings about it are of secondary importance. As a tech writer, I try to understand my users' needs and structure content to meet those needs. But I'm never going to score a home run every time. There will always be users for whom the structure that I pick is not a great fit. If they can remix the content so it meets their needs, which might not align with the needs of the majority of users — Hallelujah! Now my content can reach a wider audience than it did before.

After all, what is single-sourcing but remixing? You take the same source content and "remix" it from manuals to help to training. As a technical communication professional, you have sound ideas about what those structures are and how best to achieve them. But users may come up with remixes that work for them that your might never imagine. For me, that prospect evokes delight in others' creativity, rather than fear of loss of control.

In other words, yes, I would feel happy.

I'm always on the lookout for resources to suggest when engineers ask for help with their writing.

My first recommendation for them is the same as my first recommendation for anyone who wants to improve their writing: Style: The Basics of Clarity and Grace, by Joseph Williams, my former professor at University of Chicago. He has other variations on this title, with similar content, but this one is the shortest and least textbookish.

Another book I like is A Guide to Writing as an Engineer, by David Beer, which talks about writing in terms that engineers can relate to.

I recently came across a couple of online resources (thanks to Laura Ricci):

• Rhetoric for Engineers. There is even a Rhetoric for Engineers mailing list.


• Writing Guidelines for Engineering and Science Students

Any other suggestions?

For some reason, I've never been a big fan of "whodunnit" mysteries. In the mystery genre, I tend to prefer detective stories, where the focus is on the character of the protagonist. But I love whodunnits when it comes to intellectual subjects. I enjoy reading the history of how somebody figured something out.

A couple of examples of this are Bill Bryson's A Short History of Nearly Everything, and Richard Elliot Friedman's Who Wrote the Bible? Bryson is a consummate storyteller, so his book is much better in the parts where he tells the history of science than in the parts where he actually explains science (though it's all quite good). I'm a bit skeptical of the historical accuracy, but the stories are great fun. In Bryson's account, Newton's Principia Mathematica was written as the result of a bar bet among Christopher Wren, Robert Hooke, and Edmond Halley. Similarly, Friedman tells not only who wrote the Five Books of Moses (hint: not Moses), but also how biblical scholars came to understand its history.

Another example is filmmaker Errol Morris's series of blog articles on the New York Time website, on how he figured out a mystery behind a pair of early photographs from the Crimean war. Morris could have given us his answer to the mystery right up front, but instead he recounts the process that he went through, including numerous interviews and a trip to the site where the photographs were taken, over 150 years later. He gives large chunks of interviews verbatim from transcripts or emails, so we can see the thought processes of his subjects, as well as his own. It makes fascinating and compelling reading.

Technical writers don't usually get the luxury of telling how we came to understand the facts we present, even when it involves lots of "detective" work. We are deprived of one of most powerful and engaging tools of a writer. Humans love stories, and have been telling them since we developed language. (Indeed, they were probably one of the reasons we developed language.) Readers of technical documentation don't want to be engaged by stories. They want to get information quickly and get back to finishing what they were trying to do.

There is a story that technical writers can tell. It is exactly that story of a user who has a goal, and must accomplish a task to achieve that goal. We can tell this story in requirements documents, use cases, and usability studies. We can even tell it in tutorials. The more we can get our organizations to see the user as the hero of stories about the product, the more we can make those stories come true.

Thanks to Nancy Friedman for notice that today is National Punctuation Day. While I'm not normally one to get all het up about punctuation in anyone's writing but my own, I do appreciate the subtlety of a semi-colon and the vigor of an em-dash, appropriately placed.

One developer whose documentation comments I edit has a tendency to write with more exclamation points than explanations. For example, the documentation comment for a "Foo" class might be "A Foo!". While the enthusiasm is refreshing, I am left with the task of describing what a foo is and does, and why the reader might care.