|
When you hear the word "technical writer" what comes to mind? Computers? Engineering? Complicated subjects? I want to challenge the writing world: have you considered the idea that a technical writer can be the best resource for all of your communications projects? Let me explain why.
Technical writers are skilled at creating clear, concise text that translates complicated ideas into simple ones. This skill is great for areas like computer software, manuals, engineering documents, and other communications that need to be clear and to the point. This is a given. But what it's also great for is a wide range of communications, the most obvious of which is training materials. Training is a close cousin to end user documentation; it's just a different format. Really good training materials have not only stellar instructional design behind them, but also clear language. What if your design and ideas are great but your text comes out muddy? How will that affect your learners? Wouldn't technical writing skills be helpful in this scenario? So let's take this a step further. Would you hire a technical writer to create your marketing or web communications? Maybe? Maybe not? It may seem counter-intuitive to put a technical writer in this role, but in order for marketing or web copy to sell it has to grab attention quickly. This means not rambling. This means making sense to a wide audience. This means getting to the point, but in a creative and catchy way. Now here's where things get squishy. Have you ever seen marketing text with a bunch of flowing, embellished words that honestly aren't coherent and don't really get to the point? This is a classic case of "attempting to be creative and catchy, but in the process completely erasing any semblance of quality content" syndrome. When I was employed as a technical writer, I would often fix the work of the marketing communications person for this very reason. And honestly in the end I wound up completely taking over, because as a technical writer I was just able to create something much more effective. So when you're looking around for writing help, think about the technical writer. And not just for technical projects - but for a wide range of projects. Their unique skills can sometimes be advantageous to your communications endeavors, if you just take the time to find one who has a bit of a creative bug in their arsenal.
0 Comments
I think, as with many fields that rely on experience more than education, technical writing is a very tough field to break into. In fact any writing field is a tough field to break into. Why? Because you have to prove yourself and get solid writing experience before someone wants to hire you, but then you often need someone to hire you in order to get published.
I broke into technical writing by accident. I started as a project administrator in an IT department. They asked me to edit some documents because I had an English degree, and they loved my work. Before I knew it I was the new technical writer. Then I was managing technical publications and entire help systems, and localizing documents for clients all over the globe. I think a good way to break into the field is to get on with an IT company. Even if it’s just in an administrative role. You can get a feel for the products, try to learn more, and then ask to edit some documents or to participate in some projects. It’s a good way to demonstrate your abilities and to absorb skills from the pros. Ask questions. Ask how they create documents. Ask for suggestions about how to write more effectively. I have used this technique to move from technical to marketing communications. It shows you are interested, and usually people are happy to share knowledge. And remember, most companies would be happy to give you extra work if you ask for it and if they think you are qualified. Don’t forget that. They get more bang for their buck if there is one person doing multiple jobs. I successfully asked for, and took on, marketing projects alongside my technical writing projects because I wanted the experience and to learn the field. These skills propelled me forward and allowed me to expand my career even further. Final thought: if you find yourself stuck and stagnant in your job, keep it moving. Especially if you receive good feedback from colleagues about your writing but the company won’t let you move forward. Find a new company that will. Sometimes managers will peg you in a job because it’s cheaper for them to keep you there, or because they think you are very skilled at it (even if you are trying to move elsewhere). Need help growing your business or nonprofit organization? Browse my website to learn about how I can help you with your particular needs. The challenge with traditional user manuals is that they can often become jumbled and hard to understand. And in an effort to fix this issue, writers can try to employ what I call "look over here" techniques to minimize the wordiness and simplify the content. I have found this approach to be extremely ineffective most of the time.
Why? Because user manuals are not meant to be flipped through 10 times for one task. That is what online help is for. So how can we create a good user manual? Well, we do so by dividing the content up and presenting it in a self-contained manner. In this way, ALL of the information necessary to perform that task is present in that section of content. Take this basic scenario of a sample page from a user manual, and see if you can tell what's wrong with it: Logging into the application 1. Open the Start Menu. If you do not know how to access the Start Menu, see page 5. 2. Locate Application A, and double click to open it. For more information about how to do this, see page 2. If you do not see the program listed, go to page 6 for troubleshooting. 3. On the login screen, enter your user name. For more information about where to get your user name, see page 3. 4. Enter your password. If you have forgotten your password or are not sure what your password is, see page 4. 5. Click OK to log in. Does it look concise and pretty? Yes. Does it appear easy to scan? Sure. But is it effective? No. Why? In the scenario above, we have turned five simple steps into an extremely complex, page-flipping process whereby the user has to go from page to page in order to perform a simple task. The workflow looks something like this: page 1, page 5, page 1, page 2 or page 6, page 1, page 3, page 1, page 4, page 1. Why put the user through this? And imagine if the pages weren't close together or there were 20 steps in the process? Let's say the manual was 200 pages long, and the user had to flip from page 25, to page 72, to page 4, to page 169, etc... The best way to format a user manual is to create self-contained modules that have all of the necessary information within the module. Page flipping should be minimized. However you must be careful to format the text so that it still maintains its readability. How do we do this? By using bullets and notes. My rule of thumb is: have your main action in the step, and any supplementary instructions in bullets or a note. That way, if the user doesn't need the extra help, he/she can move forward quickly and not be encumbered by excess information. Want to read more? View my expanded blog post here, where I go more in depth on the topic. Need help growing your business or nonprofit organization? Browse my website to learn about how I can help you with your particular needs. The traditional form of help documentation is a hard copy manual that is printed out, nicely bound, and functional. It serves as a reference manual – skim the TOC or index, find the page, and follow the directions step by step. The problem with a user manual format, in my opinion, is that it is very linear.
The challenge with these types of documents? User manuals can often become jumbled and hard to understand. And in an effort to fix this issue, writers can try to employ what I call “look over here” techniques to minimize the wordiness and simplify the content. I have found this approach to be extremely ineffective most of the time. Why? Because user manuals are not set up to be flipped through 10 times for one task. That is what online help is for (see an upcoming blog post for more information about that format). As a writer trying to create a (good) user manual, it is better to divide your content up and present it in a self-contained manner. In this way, ALL of the information necessary to perform that task would be present in that section of content. Example: Bad formatting Take this basic scenario of sample pages from a user manual, and see what’s wrong with it: Page 1 Logging into the application 1. Open the Start Menu. If you do not know how to access the Start Menu, see page 5. 2. Locate Application A, and double click to open it. For more information about how to do this, see page 2. If you do not see the program listed, go to page 6 for troubleshooting. 3. On the login screen, enter your user name. For more information about where to get your user name, see page 3. 4. Enter your password. If you have forgotten your password or are not sure what your password is, see page 4. 5. Click OK to log in. Does it look concise and pretty? Yes. Does it appear easy to scan? Sure. But is it effective? No. Let's take a look at the other pages the user has to visit in order to complete those concise steps on page one. Page 2 Locating the application Open the Start Menu and select the application from the list. If you do not see the program listed, go to page 6 for troubleshooting. If you do not know how to access the Start Menu, see page 5. Page 3 Getting your user name Your user name is sent to you by your administrator. If you have not received your user name, contact your administrator for assistance. Page 4 Your user password Your user password is given to you by your administrator, and you can change it through the Preferences page. Refer to your administrator email for the password, or contact your administrator for more assistance. Page 5 Accessing the Start Menu The Start Menu is located at the bottom left corner of the screen in your Windows application. Click it to access the Start Menu. Page 6 Cannot locate the application If you have installed the application but do not see it in the Start Menu, contact Customer Support for assistance. Big problems In the scenario above, we have turned five simple steps into an extremely complex, page-flipping process whereby the user has to go from page to page in order to perform a simple task. The workflow looks something like this: page 1, page 5, page 1, page 2 or page 6, page 1, page 3, page 1, page 4, page 1. Why put the user through this? And imagine if the pages weren’t close together or there were 20 steps in the process? Let’s say the manual was 200 pages long, and the user had to flip from page 25, to page 72, to page 4, to page 169, etc... Example: Good formatting Let’s create user manual text that is effective. Here is a better version of the above information: Page 1 Logging into the application 1. Open the Start Menu, which is located at the bottom left corner of the screen in your Windows application. 2. Locate Application A, and double click to open it. Note: If you have installed the application but do not see it in the Start Menu, contact Customer Support for assistance. 3. On the login screen, enter your user name. Note: Your user name is sent to you by your administrator. If you have not received your user name, contact your administrator for assistance. 4. Enter your password. Note: Your user password is given to you by your administrator, and you can change it through the Preferences page. If you have forgotten your password or aren’t sure what your password is, refer to your administrator email for the password, or contact your administrator for more assistance 5. Click OK to log in. In this scenario, we have included all the necessary information in a single page. The user doesn’t have to flip around, and they can complete the process much more quickly and easily. But what about the other pages? Ideally, we would likely still have the other pages present (pages 2-6). The key is that we do not require the user to visit those pages as part of this particular process. The user would go directly to those pages for specific problems, and would find those pages via the TOC or index. And what about readability? Is it more wordy? Yes, a bit. But that doesn't have to be a bad thing, if you know how to format your text. What’s the best way to help readability? Use notes and bullets to make it easier to scan. My rule of thumb is: have your main action in the step, and any supplementary instructions in bullets or a note. That way, if the user doesn’t need the extra help, he/she can move forward quickly and not be encumbered by excess information. Look back at the example and you will see how easy it still is to scan, even with the excess information. So you want to be a good technical writer. Ok. But what does that entail? What is good technical writing vs. bad technical writing?
I’ve seen a lot of software engineers attempt to write help documentation. And a lot of companies try to save on cost by having them do so (not a good idea). During my career I have learned something very important: technical writing is a skill that must be developed, and not everyone is capable of good technical writing. And something else I have learned: you need to be a good writer, first and foremost, before you can be a good technical writer. You must have the skills to not only translate technically challenging information into common language, but to use the English language appropriately in pursuit of this goal. So how can you become a better technical writer? Or better yet, want to know some technical writing basics? Here are some tips. 1. Know your audience. Are your end users technically savvy people? Or are computers completely foreign to them? Knowing the answer to this question is important for determining how you need to present your material, and what level of detail you should provide. If you have a very savvy audience, then you can use more complex ideas and omit some basic information (such as, what a user name is). If you have a group of users who have never before accessed a computer, then you would need to go into more detail about basic use (i.e., explaining what a user name is) and you would want to omit information that is way above their knowledge level. 2. Use direct language. Tell them what to do. Use “click here to continue” rather than “the button should be clicked to continue”. 3. Get to the point. The worst technical documents are wordy, wordy, wordy. Good technical writers know how to condense their material into the shortest possible sentence/paragraph without losing meaning. This is not always an easy task, depending on your skill level. But do make an effort. For example: Bad technical writing: Scroll to the bottom of the page and locate the Submit button, which you will then click to submit your information to the database. Good technical writing: Click the Submit button at the bottom of the page to submit your information to the database. What’s so bad about the first example? Wordy, bumbling, and indirect (“which you will then click”). What’s so good about the second example? Clear, to the point, and succinct. You don’t need to tell the user to scroll down if you say that the button is at the bottom of the page. The user will know they need to scroll in order to get there. So take it out – it’s a waste of space and words. More tips to come. |
Contact me at [email protected].
Welcome to my blog. Please use the Category links below to find topics of interest to you, or just scroll through current postings. Receive new postings via email:
Categories
All
Archives
November 2014
|
RSS Feed
