Technical Writing, Documentation, and Training

404-873-4288

Tag Archives: word choice

T.S. Eliot dedicated the “The Waste Land,” arguably one of the most important poems written in the 20th century, to Ezra Pound for his timely edits. According to Richard Ellman, Pound persuaded Eliot to remove several poems that Eliot had inserted between the stanzas of “The Waste Land.” As Pound said, “the longest poem in the English langwidge [sic]. Don’t try to bust all records by prolonging it three pages further.” (From “The First Waste Land.” In Eliot in His Time: Essays on the Occasion of the Fiftieth Anniversary of The Waste Land.” Princeton, Princeton UP, 1973.)
Continue reading

Good writing is clear and precise. Good technical writing, to borrow a phrase from the young people, is totally clear and precise. Let’s be real: most people don’t bother reading technical documentation until they’re stuck and don’t know how to proceed. Enter this? Press that? “What do I do now?” Unfortunately for those sorry folks, their foray into the user manual or online help is often not a good experience. The reason: the explanation is not clear and/or precise. Such is the state of my chosen profession.
Continue reading

Technically speaking, technical writing is writing, but all writing is not technical. Consult the textbooks and you’ll find much material describing the difference. Consider, however, the possibility that technical writing is not writing at all.  Compare, say, Moby Dick to your latest furniture assembly instructions:
Continue reading

These days, business speak surrounds us. It doesn’t discriminate against company size or position status. College interns and CEOs alike find themselves dropping buzz words in conversation. But to what end? When is enough, enough? The next time you want to move forward, deliver, or buy-in by all means go for it. But don’t expect people to know what you’re talking about. The more time your employees spend guessing the meaning behind your jargon, the less productive they are. Ben Franklin sums it up best:  “Time is money.”

Continue reading

It’s not like technical writing isn’t already incredibly boring, so why does it have to be consistent? Such is the typical complaint about what we at Shoap do to earn a living. So how important is consistency?

While we sometimes fantasize about people grabbing one of our documents and cozying up to the fire to spend some quiet hours learning how to use a new piece of hardware or software, the reality is starkly different. As they used to say about Ivory soap, 99.44% of the time the only reason people crack a user guide or click on online help is because they’re stuck: they can’t figure out how to do something that they need to do – and need to do immediately. 

Consistency means you can find information quickly and understand that information when you encounter problems. Let’s see how.

Continue reading

Why do people use the passive voice? Engineers, scholars and business people alike use the passive voice on a daily basis – probably without even realizing it. So then, why is passive voice frowned upon and what exactly is it?

Simply put, passive voice is a style of writing that makes the object of the sentence the subject of the sentence. Sentences written in passive voice are structured so that the noun who performs the action is not the subject. Confused? Consider this illustration.

Sentence 1: I made a mistake (Active)
Sentence 2: Mistakes were made. (Passive)
Continue reading

How the Audience Affects Technical Communication

Paul Clifton is a Ph.D. student in Digital Media at the Georgia Institute of Technology. He has been an on and off technical writer with Shoap Technical Services since 2007 and is currently working in interaction and user experience design at Intel.

Recently, I helped my friend update his resume. I’d helped him make a brand new one a few years before, and it had been an extremely painful process, so when he asked me to help update it, I nearly just said no. To my surprise, the draft he sent me proved that he had been paying attention when I had originally explained the rules for making a good resume, why they were the rules, and why following them mattered. His grammar and spelling still weren’t very good, but grammar and spelling are the easy part. Clearly communicating complex information by meeting the expectations of the reader is the hard part, and I was happy to see that he had pretty well taken care of that.
Continue reading

By the time you enter the 3rd grade, you know what summer is. It’s that time of year when you don’t have to go to school or do homework. Instead, you can just play all day with your friends, go on vacations, watch TV, or anything else you’d like to do. Summer is always a time of relaxation, an unwinding from all the busyness and tension of the school year—even at the age of 7. It’s exactly what summer should be—lazy and carefree. Summer break is a break for a reason, right?
Continue reading

Do you know about Wikipedia’s Simple English?

I don’t know about you, but I’m constantly Googling anything and everything and I frequently end up on Wikipedia’s website. One day I was looking at all of the possible languages I could read an entry in and noticed “Simple English” was one of the options. I was reading about something complex and “Simple English” simplified the topic and made it easier to understand (you could say it’s a “red carpet” to the “English” entry).

Continue reading

How Documentation Can Create Trust

When you are a company dealing with your customers’ most valuable personal information, you need them to trust you. One easy way to do this is to have your documentation flawless (or close to it). Also, performing a test run with a small group of people before releasing it to the masses is a good idea. The group of people should be 3rd party users who can find the mistakes you can’t find (since you’ve read and reread the form 40 times and never want to see it again).

Continue reading