|
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.
2 Comments
Part four in the "Common Grammar Mistakes" series. Last time we talked about their vs. there vs. they're. Here, we discuss another common grammar mishap.
It’s vs. Its Finding the correct usage for these two words can be challenging to some writers. But it need not be. The difference between “it’s” and “its” is that one is a contraction and one indicates possession. It’s is short for “it is” or “it has”. You would use “it’s” in the following scenarios:
Part three in the "Common Grammar Mistakes" series. Last time we talked about to vs too. Here, we discuss another common grammar mishap.
Their vs there vs they’re The difference between these words is fairly straightforward. Their – indicates possession, for two or more people/things.
Part two in the "Common Grammar Mistakes" series. Last time we talked about "loose" vs. "lose". Here, we discuss another common grammar mishap.
To vs. Too These two words have completely different usages, even though they sound the same. Here is a quick way to remember the difference: If you are talking about an excess amount or an additional item, use “too”. In all other cases, use “to”. Too is always used to indicate something additional or excessive, or if you can substitute the word "entirely". Examples of excess:
Hint: if you can substitute the word “as well”, then you should use “too”.
Next, we will talk about "their" vs. "there" vs. "they're". 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. Many novice (and even some experienced) writers make mistakes when it comes to things such as apostrophes, an extra “o”, or possession. Here are some of the most common mistakes I see people make, and how to choose the correct usage.
Lose vs. Loose This is perhaps one of the most common (and most aggravating) mistakes I see writers make. The word “loose” is often incorrectly utilized in place of “lose”. What is the difference? Lose is a verb, meaning to no longer be in possession of. Or, in the case of team sports, it can mean the opposite of “win”. Correct usage of “lose” I’m going to lose my mind. Losing my job has been really difficult. I think we are going to lose the game. Loose is an adjective, and is used to describe something. In most cases it means the opposite of “tight”. But there are some special uses. Correct usage of “loose” The bolt is loose. I have a loose button on my shirt. That movie is loosely related to the book. Next, we will talk about "to" vs. "too". Creating an effective website is more than just creating a snazzy look. These days, designers may be quick to create sites that provide fancy graphics, smooth transitions, and other nice-to-look-at features. And this is good, because first impressions are important. But they aren’t everything.
In fact, a fancy and professionally designed website will not guarantee an increase in your business. Furthermore, focusing more energy on the look of your site rather than the content will not perform well for your business at all. How is this so? Presenting item A: SEO. For the non-techie people, this means “search engine optimization.” Search engine optimization is the process of creating content, tags, linking, and other non-design elements that increase traffic to your site and improve your Google/search engine rankings. This is done via targeted content, carefully selected key words, and meta keywords/meta tags in the HTML code. Presenting item B: Content Sometimes even if the SEO is good, the content itself will actually cause zero increase in your conversion rates. What is website conversion? Website conversion is the process of creating website traffic into actual business. Good content is an essential part of this process. You only have seconds to make an impression and engage your readers with your content; if you have attracted the traffic but lose them at the first page of your site, you have a problem. Presenting item C: Layout A good website presents material in a way that is easy to scan, is well organized, and allows the visitor to quickly locate the information they are most interested in. If you are targeting several different markets, it is key that every type of client from every type of market can quickly find the information they are looking for. Ideally, from the home page. Creating an effective website is one of the most important things you can do to increase your business. Invest well. A lot of inexperienced writers looking to break into freelance or book writing wonder...how can I become a good writer? What does it take? Is there some kind of formal process I need to go through in order to write well and get my work noticed?
Good writing vs. great writing The truth is, good writing takes practice. I believe that most people are capable of good writing, and that only a few people are capable of spectacular writing. No matter what the genre (business, creative, non-fiction, etc.), this theory seems to hold true. Case in point #1: Of all the books published every year, many are good (obviously, or they wouldn't be published at all right?). But how many become best sellers? And of those, how many actually win literary awards? There are plenty of good book writers, few great ones. This is a trend that goes back to the ye old days of Shakespeare, who in his time never achieved the literary acclaim he has now. Case in point #2: I have seen non-writing business colleagues create marketing materials or implementation guides that were actually fairly good. But I've also re-worked documents from colleagues (including colleagues supposedly specializing in marketing communications - yikes) that lacked flow, structure, and general grammatical accuracy. Good writing exists, great writing is hard to find. So what can you do? Practice, practice, practice. Writing with correct structure, and with interesting words. Break out the thesaurus (there is one available in Microsoft Word) and find a different way to describe something. This is one of the best tools you can use to make your writing more interesting. The importance of good communication Beyond grammatical accuracy, interesting content and language "rules" (which honestly, good writers sometimes completely ignore), a good writer is first and foremost good at communicating. If you have trouble communicating via speech, you will have trouble communicating via the written word. Whether you are writing marketing collateral to sell something, training materials to teach something, a book to tell a story, or an RFP for a client...if you cannot get your message across with your words, you have failed as a writer. How can I improve my writing? My three biggest guidelines: #1: Read. And read a lot. You will increase your vocabulary and your ability to craft material. I recommend reading some of the classics, or some of the award winning novels you can find via the New York Times listings. These books will have the best examples of excellent writing, not just good writing. #2: Practice. In all my years of writing, I still have things to learn. New approaches, new techniques, new presentation. It takes practice to create something truly engaging for the reader. So write, and write often. #3: Consider a writing class. If you don't know where to start or are interested in creative writing (novels, poetry, short stories), a class at your local community college can help you get moving. |
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
