Shoap Technical ServicesTechnical writers are a rare breed. To be successful in this profession, you have to be patient, know how to communicate, and, last but not least, understand technical concepts. These tough demands have been the inspiration for this article, the third and final, in what we like to call our technical writing “rant topics.” See the first two in the triptych, “What’s Wrong with the Passive Voice” and “Why is Consistency Important.”
So, what makes technical writing such a challenge?
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)
After an eighteen year career in technology, I have one thing in common with many of my colleagues: we have children. Eating lunch or grabbing a coffee I am frequently asked “What should my child do to get a job in technology” and “What did you major in?” and “I heard about a computer camp where kids make games. Is this a good idea?”
I have little recollection of how I decided to become a technical writer. I’m not even sure how I found out that technical writing was a thing people did. I followed some roommates from college to Atlanta from Connecticut in the fall of 1993. I was a pretty good writer and I had always been a “computer nerd.” Today that might conjure up visions of Red Bull fueled hackathons. When I was growing up it meant reading operating system manuals. For fun.
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.
“Waterfall is dead, long live Agile,” many voices cry, heralding a transition in the software industry from heavyweight engineering efforts to an almost sports-like scrimmage. Waterfall didn’tkeep up, they complain. Projects turned into congested pipelines and out of desperation to reclaim fluidity, the entire cycle broke down into an environment of iterative re-development that gave birth to Agile. Increasingly, developers collaborate in short sprints to rapidly address evolving concerns rather than as construction crews working from blueprints. What does this new era mean for technical writing as part of software development? More specifically, what is expected of an Agile Technical Writer?
In a recent issue of the Shoap Technical Reader, I commented on my reaction to a usability test in which I had participated (“Why Technical Writers Are So Weird”). The test was for one of our writer’s web UI development classes. He created an application to create a response to an RFP. His observations can be found here: http://superawesomegood.com/2012/03/31/searchers-and-scrollers/.
You may have heard the term “gamification” floating around and wondered, “What is that?” The answer: Gamification is the new buzz word representing the idea of incorporating gaming concepts and techniques into non-game activities in order to drive a desired behavior. Marketing campaigns can use game mechanics to drive customers to their websites, sales agents can participate in games to drive competition and increase sales, and in our industry, documentation and training groups can build game-like training materials to fully engage the learner.
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).
There is an unfortunate trend towards using more images and icons and using fewer written instructions (I like to say “words”). Personally, I don’t think it’s obvious what every icon actually is and what it means, especially when I’m in a hurry to do something.