Recently, a prospect called us about a training guide he needed written for a new enterprise application his company had recently purchased and was trying to implement. Unfortunately, he had already paid the company that developed the application to create training materials but found, once he had a chance to review the materials, that they were not only impenetrable and useless from a user’s point of view but mostly incorrect as well. A complete waste of money. Alas.
Tag: Rants
For additional information regarding Waterfall/Agile development and how it impacts technical writing, please refer to previous blog posts written by Eric Sedor and Shaun Kelly.
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?
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.
Take a look at this picture of the keyboard on my Dell Studio 1558 laptop (shown above). Notice anything odd?
Well, where’s Number Lock? What happened to the numeric pad (usually shares keys with the 7, 8, 9, U, I, O, J, K, L and M)? These keys are typically used to type alt code combinations for characters not represented in the English keyboard. A Spanish speaker like yours truly would use them to type the letter “ñ”, accented vowels, and the “upside-down” exclamation and question marks.
The first time I tried to use alt codes with the laptop I thought: “I must be missing something. They must have come up with some hip new way to do it.” But how?
It turns out that in their infinite wisdom, computer hardware OEMs have decided to start eliminating features that customers “don’t want” (specifically, the Number Lock and Scroll Lock keys) in order to replace them with things that we just can’t live without, like the Windows key, a disk ejection key, or a right-click menu key. Fortunately, my manufacturer’s support staff offered some ‘helpful’ alternatives like using the Character Map or changing my keyboard language anytime I wish to type a non-standard character. Alternatively, they offered to return my ability to type accented characters in exchange for a ransom payment of $18.99 for a Targus USB numeric pad.
I still haven’t been able to decide if I’m more frustrated by the removal of a feature that I ‘don’t want,’ the support staff’s absurd ‘solutions’ to the problem that the removal of this feature has created, or the manufacturer’s complete lack of awareness of the message that it sends: “typing in any language other than English on your U.S.-market laptop will not be tolerated.”
So let this be a lesson: if you or your employees value the ability to type special characters quickly (whatever the reason may be), make sure you add the Number Lock Key to your list of features to consider for hardware purchases. It doesn’t come standard anymore.