by Overview
In your User Documentation, you direct your Reader to perform tasks with your product. If you don’t tell your Reader what to expect when performing those tasks, you will have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support.
Example: Reverse osmosis water filter
I bought and installed a Reverse Osmosis water filter. The instructions told me to fill, and then empty (the instructions foolishly used the term dump, which would have caused the destruction of the system) the tank.
The filter had a capacity of about 100 gallons per day. Thus I expected the initial fill (4.5 gallon tank) to take less than one hour. After about an hour the tank was still filling. Worried, I called the technical support. I was told that it takes about two hours for the tank to fill.
One line in the User Documentation would have eliminated that call: “The tank initially takes 2 hours to fill.” Not knowing what to expect I, and perhaps other Users, wasted the time and money to call the technical support line.
Example: Upgrading a router’s software
I had some problems with my Cable/DSL (Internet-Ethernet) router. The internal control panel made it easy to check for and download updates to the internal software. The system told me that it would take a few minutes to check for updates (good), but it did not tell me how long the update would take to perform once I downloaded the file.
Not telling the User what to expect in terms of time is a mistake. I started the update and after a few minutes of operation (was it working?) I canceled the process. I re-started it again, and decided to wait longer to see what happened. It took a few minutes longer, and successfully completed.
It would only take a simple phrase such as “the software update can take up to five minutes to complete” to reduce the User’s anxiety.
Progress indicators (as displayed in a windowing environment) are often useless. Some go beyond 100%, others are logarithmic: they move quickly in the early processing and wait, seemingly at the end, for a long time while processing is completing. Consider making progress indicators relate to the time of operation, not number of files.
Some progress/activity indicators have nothing to do with the program they are associated with. I have used virus checkers that have abnormally terminated, yet the activity indicator kept on moving. Make sure that progress/activity indicators do reflect activity of the associated program.
File downloads do it
Telling the User what to expect is not a new concept. If you have ever downloaded files, the download site will often tell how long the file will take to download, based upon your Internet connection.
Example: Your product’s indicators
While most examples of telling the User what to expect deals with the time needed to complete an activity, others can be related to the indicators and performance of the product.
I have a small smart battery charger that has a red light for each of the battery positions. Unfortunately, the operation of these lights is impossible to understand, and there is no description of how they work.
Here’s what happens. When you first insert the battery, the light illuminates. A short while later (the charging still has many hours to go), the light goes off. Sometime toward the end of the charging cycle the light may go on again.
This is clearly confusing to the User. The User’s expectation is that when the light goes out, the charging is completed. This would result in a lot of User frustration, as Users would try to use “charged” batteries that were not charged. The developers of the battery charger should explain the operation of these displays.
The bottom line
Tell the Users what to expect as they use your product. Often this information is the amount of time it will take for an operation to complete. For other products, you may have to tell the User what the indicators mean.
Don’t leave your document Readers confused or left to figure things out on their own. Doing so will reduce your Users’ comfort with your product, and increase your technical support costs.
About the Author:
Barry Millman, Ph.D., has a Bachelor of Science in Electrical Engineering (1966, Carnegie Institute of Technology) and an M.Sc. and Ph.D. in Psychology (Human Information Processing, University of Calgary). He has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker. For the past seven years he has been researching and creating resources to help organizations create great User Documents.
Visit: http://www.greatuserdocs.com/ for resources to help you create the User Documents that your Product needs and your Users deserve.
Visit http://www.greatuserdocs.com/ReadingRoom.htm for more articles like this one.
Article Source: ArticlesBase.com – Great Technical Writing: Tell your Users What to Expect
]]>
The field of content writing serves as a very important feature in a website. The main reason people visit the site is to search for information on different goods and services. Audiences will be satisfied if they get informative and satisfactory content on one’s site. Besides this, a site needs to be well designed as well with information-rich content in order to drive more traffic.
Easy and simple language is the prerequisite of any content. There are a few pointers that need to be reminded at all costs in order to excel in the field of content writing. The first and foremost point is to ensure that the language of the content is in accordance with audiences for whom the articles, reviews or blogs are meant.
For example, if a content writer intends to write a promotional article, then he needs to know the nature and services offered by that particular business and its technical terms in order to make the best promotional style content. Also, a very simple and easy to understand language needs to be used in writing content for the sites so that even the lay man can easily get to know what the content is all about. The writer needs to think from the place of the reader and offer complete information.
Essentials of content writing – authenticity, organization and numbering.
Organization of content is also very crucial and includes proper designing and formatting of the information gathered from various sources. The writer can write an entire article in a single paragraph or can even make the content easy to read by arranging the headings. The relevancy of pointers needs to be properly handled so that the audiences can analyze distinction of paragraphs.
Numbering and bulleting needs to be used in the content to highlight the most important points. This will automatically make the article effective along with breaking the visual monotony.
It is wise to use the conversational language as it helps the readers to feel more involved in content thereby motivating them to continue reading the article.
In addition, the authenticity and originality of the content needs to be considered wisely because offering wrong or prejudiced information to readers can in turn provide negative or incomplete impact.
Needless to say, to be a successful and popular content writer, it is very imperative to have that passion and flair to write. Until the writer is extremely passionate about his or her job, they can produce only mundane and dull content. so, follow these simple and beneficial tips in order to write exceptional content for the targeted audiences.
About the Author
Visit sem-infotech.com for content writing services, ppc management and professional seo services.
Article source: http://www.articler.com/
]]>
The other day, I managed finally to watch Clint Eastwood’s Gran Torino with some friends of mine. One of the scenes reminded me of issues faced when writing documentation: What do you leave out?
To set the scene, Clint’s Eastwoord’s character, Walt Kowalski, is a gruff Korean War veteran and retired Ford autoworker still living in his older neighbourhood that is quickly being repopulated with Hmong immigrants and gangs. After a failed burglary and gang initiation, Walt’s teenaged next-door neighbour (Thao) comes to apologize, and to work for Walt as both punishment and compensation.
Walt is a very self-sufficient man, keeping his property and belongings well maintained, and generally sitting on his veranda drinking Pabst Blue Ribbon. As such, he has no work for Thao—until he surveys his neighbourhood a little more and sees the disrepair into which many of the houses have fallen. He gets Thao to repair the roof and eavestroughing of the house across the street.
At this point, one of my friends, an intelligent, well-educated nursing manager and operating room nurse, asked, “Why that house? Why is that house important?” And it wasn’t so much that the house was important, but the audience is expected to realize that Walt has become tired of sitting on his porch staring at his old neighbour’s house falling down across from him.
But could Eastwood (as the director) not have included a short scene where Walt and the new neighbour across the street have words about the state of the house? Or where Walt makes a specific comment about having to stare at that particular house as it falls down? Would it really have made a difference to the story, or most people’s understanding?
We make decisions like this every day. Whether it’s to include a word in a glossary or index, add an introduction or conclusion to a procedure, include a screenshot or even to write for a particular audience. There’s always a choice to be made that will either add to the understanding of a document or take away from it. These are especially important decisions when factoring in budget and time constraints:
- Do we have time to change the glossary or index?
- Can we afford to print more pages?
- Do we have time to write more introductions and conclusions, and get them reviewed?
- Is there time to get and properly edit the screenshot?
- Can we rewrite for a novice audience or do we continue writing for the expert audience?
While I’m certain we’d all love to write the perfect document every time, in the end, the original planning and analysis should have accounted for all of these issues. Something may have been missed, but it must become part of the post-project review, something to consider for the next time.
Movie-makers don’t get a second chance to make a movie, but much of our documentation can be revised later and having a solid review to work from is an excellent starting point.
How do you make sure you get all the right information into your documents?
Image courtesy Ian Britton | FreeFoto.com
]]>
Seriously, I had a dream about useful communication. I think by the time I tell this story it will seem pretty trivial and uninformative, but it’s a story I really feel like telling.
In my dream the other night, I was part of a team transferred to an existing department. I seemed to be in a hospital and I seemed to be a doctor, but not being a doctor nor working in a hospital, I’m not certain.
The existing department had a ritual of singing a particular song at the beginning of meetings and my team was expected to sing it. This was supposed to be some kind of team-building exercise. Unfortunately, no one on my team was familiar withe the song. And, like the national anthem at sporting events, only a few people around us seemed to be singing, and were mumbling. The whole affair seemed to be some weird Gregorian chant.
My team certainly did not feel like they were part of the larger group in this so-called team-building event; I chose to speak up about it. (Generally in my dreams, I’m unable to speak at all.)
I was very eloquent in my argument that if this was to be a team-building exercise then it would be more useful to ensure that the whole team be involved. The department could have:
- supplied my team with the lyrics to the song,
- ensured that their members knew the lyrics and would sing them clearly,
- chosen a song that would be familiar to a larger group, including my team, or
- found some other way to welcome us to the team.
This reminds me of my audience analysis post, without being directly related. It’s essential to any communication to know your audience; if anything, know what they already know and speak to what they don’t. And people will be much more engaged when the communication is obviously intended for them.
Image by Free-StockPhotos.com
]]>
I love writing and I’ve been looking at ways to expand my audience, so I’ve been looking into freelance writing. But, man, there are a ton of freelance writing scams out there!
Some of the sites I found require an “application” or “registration” fee (e.g., freelancehomewriters.com). Really? Shouldn’t the site be making money from me writing for them? Then I found a lot of blogs and posts (e.g., freelancedaily.net, Scams, Warnings, Deadbeats) that actually document the scams as well as the deadbeats who just don’t pay for the work.
I found a pretty good eHow article about avoiding freelance writing scams; step 7 was pretty much number 1 for me:
If they ask you for money, then writer beware. The basic principle of any job is that the employer pays the employee, not the other way around.
Searching for information about freelance writing scams led me to Men with Pens and essentially an admonishment to save my money. Generally, if someone’s willing to share their “get rich quick” system with you for a “low-low price!”, it’s a scam: they’re getting rich by stealing your money!
My top 3:
What are yours?
]]>
When a technical writer prepares to update or write new documentation, an audience analysis is probably one of the first things he does. Unfortunately, it involves a lot of guesswork. Does he want to interview users and get answers to his questions?
- What does the audience already know?
- What does the audience want to know?
Or can he proceed based on a few educated guesses?
What does the audience already know?
Really, does a user even know what he knows? How many interviews is a technical writer prepared to conduct to extract sufficient information from the audience?
What the technical writer is probably going to find out is that some users are experts, some are novices and the rest are somewhere in between. So, how to write for the novice without condescending to the expert?
The easiest solution is simply to write for those in between: assume the user has seen the process and (a) either needs a short refresher or (b) will follow the documentation while performing the procedure. In either case, the documentation can be exactly the same.
What about other types of communications? The same process applies: the novice will need to read the communication in its entirety and the expert will be able to skim it for the important ideas.
What does the audience want to know?
But what information actually ends up in the documentation or communication? In a standard software user guide, for example:
- What does the software do?
- How to install or uninstall it?
- How to configure it?
- When to use its myriad functions?
- What to do about error or warning messages?
- Who to contact for support?
Yes, generally all of these questions need to be answered all the time.
But because the expert will probably know the background information, and because the novice won’t need it immediately to perform a procedure, it can be included in an appendix, if necessary. As well, by writing task-based procedures, all the users can follow the procedures to perform a specific task. An index will lead the user to the appropriate procedure related to a specific function. And a glossary will assist novices with unfamiliar terminology.
The audience analysis becomes much simpler once the basic concepts of the document are determined: a reasonable knowledge of the average user is sufficient to begin the documentation process. This should already be available based on the project and the reason for it.
Here are few resources for audience analysis:
- wikiHow: How to Conduct Audience Analysis
- Online Technical Writing: Audience Analysis
- Wikipedia: Audience analysis