Moving a product out the door to capitalize on market demand is a necessity – it’s simple economics! Consumers demand constant product improvements. This “out with the old, in with the new” mentality has led many successful companies to switch from Waterfall development to Agile. What does this mean exactly? For the uninitiated, use this simple analogy. Waterfall development can be compared to a marathon. All software features are built in one long process and then errors are fixed. Agile development is more like a series of sprints. Software is released in a series of small iterations. Each release includes a few added features, and errors are corrected along the way rather than at the end. As you can imagine, the switch to Agile development completely shatters the status quo and roles of people associated with the development teams. This led us to wonder: Specifically, how does the switch to Agile impact the role of technical writers?
When clients tell me that they can write their own user manuals because, after all, they say, they already know how to write, I’m reminded of a quip from an old friend, frustrated by his software developers’ inability to complete a payment application on time: “Why does it take so long? It’s just typing.” Sadly, I sometimes think, people think the same about technical writing: It’s just typing. Which got me thinking: What does a good technical writer have to know to be a good, dare I say, great technical writer?
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.”
Technical 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?
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.
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)
In an earlier article (http://www.shoap.com/rfp-responses-go-technical), we discussed the importance of responding to RFPs with correct, easy to read and understand responses. Several of our readers wondered if there were any tools that could help them address the arduous task of responding to RFPs. This article is for them.
Unquestionably, there are more onerous tasks than responding to a big, fat request for proposal (RFP). Unfortunately, I just can’t think of anything. People who have to do this for a living spend countless (and thankless) hours, ensuring the response is correct and flawless. These responses can go for hundreds of pages, require inputs from various and sundry departments within the organization, and are under tremendous time constraints. It’s stressful just thinking about it. Many companies, however, are facing this nightmare head-on by investing in software that automates the process. Leave the copy/paste method behind.
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?
Who doesn’t like videos? From the silliest ones on America’s Funniest Home Videos to how to cook a turkey (one of my personal favorites which I come back to every Thanksgiving), there’s a video for everything you ever thought you wanted to know about – and lots of things you didn’t. Due to the popularity of these videos, technical communication has seen its share of examples. When you’re stumped on how to post an expense in QuickBooks, for example, you only have to Google the question and wait the requisite 0.20 seconds for the 400,000,000 results.
I used to take Microsoft Paint for granted. I saw it every once in a while in the Accessories folder when I was looking for the Calculator or Notepad but never really used it. Then I starting using screen capture programs at work to take screenshots for user guides, manuals, online helps, etc. When I was on my personal computer, I had no idea how to take a screenshot without a fancy program, and then I finally remembered Paint. Since then, I’ve used it for screenshots, creating and editing pictures/photos, and testing.