I used to work as a technical writer for a software company. It didn’t do much for my social life. I’d get talking with a personable stranger; after a while the question of my profession would come up. With a sense of impending doom, I would confess the ghastly truth.
‘Oh, so you’re that guy’ would be the reply, as my newfound and soon-to-be-lost friend looked at me with a suddenly hostile expression. At this point, the conversation would come to an end and I would be left alone to nurse my bruised ego.
Depressing as it was, I couldn’t really blame the technical writer-phobics for treating me like a leper. All too often, technical writing is just too much technicality and not enough writing.
The first problem the hapless newbie user faces is finding the relevant information in a sea of opaque headings and category titles. Once the user actually clicks through to the topic they need help with, the next problem arises: it just doesn’t make sense. The help text is so steeped in technical jargon that it would take a highly skilled software engineer to decipher it. Well, most people use software to enable jobs that they are already highly skilled at, from investment banking to graphic design. They don’t have the time to learn about a whole new, complex vocabulary area. Or to sort through a cumbersome, opaque index to find the topic they want to learn about.
What they need are the facts, and fast.
There are a few basic rules of thumb you need to follow, as a technical writer, to overcome these problems:
1. Step into the user’s shoes
What the industry describes as a state-of-the-art multi-tasking core banking tool is simply ‘that thingy on the PC into which I enter the account balances’ to a bank teller. Or imagine you’re a retired senior citizen, trying to take a photo with a webcam and send it to your grandchildren via email for the first time. That’s the perspective you have to work from. Figure out what your end-user will need to do, and how much he or she is likely to know about how your application works (this will probably be very little), and build from there. Don’t assume anything – explain everything.
2. Organize the data.
When you begin a documentation project, you’re confronted with a lot of raw information. Design documents, use cases, test cases, interviews with subject matter experts, hopefully even the application itself. Where do you start? If you answered ‘by writing’, you’re wrong. First familiarize yourself with all the information. Play around with the application for a while. Then draw out a table of contents. Start with the basics – installing the application (although an installation guide is often separate from the main help system), opening it and accessing basic functions. Then move up to more complex, specialized functions. Web designers follow something called the three-click rule – no web page should be more than three clicks away from the home page. If you’re creating an html help system, follow the same rule. Once you’ve mapped and organised all your data, you’re ready to start writing.
3. Write English
This isn’t as obvious a rule as it might seem to be. Programmers seem to be as much in the business of generating jargon as writing code. This is fine so long as technical people are communicating with other technical people. But go back to our first rule, and put yourself in the end user’s shoes. Your end users might use a highly specialized and complex argot that relates to their own profession. They probably don’t use tech jargon, or IT-speak. Some of the users might be new both to their job and to the application, so they may not be well-versed in their own industry’s jargon either. That’s where you step in, translating various layers of complex jargon and technical language into plain, communicative English. Keep it formal, brisk and businesslike. But keep it clear and simple, too. You’re being paid to explain, to instruct, not to weave webs of complex, fancy words.
There are several good books and web resources available that deal with Plain English such as the Microsoft Manual of Style for Technical Publications.
Finally, take a deep breath, sit back and read what you’ve written. Does it make sense to you? Can you bear to read it without wanting to scream out loud or throw your hands up in despair? Does it successfully make really complex things seem really easy? Do you need a glossary to understand it? Do you need someone to help you with understanding the help system?
Better yet, find someone in the office who has a little free time (impossible, I know, but try. Here’s a tip: business analysts are the best bet for this. They have to maintain a balance between technical knowledge and end-user insight too) and ask them to try and use the application referring to your help system. If they can’t figure something out, go back to the drawing board and fix things.
Yes, these are very broad rules. But very simple, and sound, basic principles are the most useful in achieving very complex tasks. Make these basics a daily part of your job as a technical writer, and you’ll find they hold you in good stead. Then maybe, one day, when someone gives you the cold shoulder at a social gathering, you can look at them with a cold sneer and reply:
‘You know the guy who keeps the business world going by showing professionals how to use applications and gadgets to work better? The guy who makes the world a better place by showing people how to use technology to do more and get more out of life? Yes, you’re right. I’m THAT guy.’
Chillibreeze's disclaimer: The views and opinions expressed in this article are those of the author(s) and do not reflect the views of Chillibreeze as a company. Chillibreeze has a strict anti-plagiarism policy. Please contact us to report any copyright issues related to this article.
Out of 5 “chilies”, our editorial team gave this article...
—About our writer:
Jayaprakash writes for chillibreeze.
>> Read more articles written by Chillibreeze writers:
