Home

What`s wrong with technical documentation

image

Contents

1. A Shoap Technical Services Whitepaper Shoap Technical Services 730 Peachtree St Suite 660 Atlanta GA 30308 Email info shoap com Phone 404 873 4288 What s Wrong with Technical Documentation Documentation must be an all inclusive answer destination Research shows that 40 percent of complaints on technical help lines come from customers having inadequate information that is they cannot even find the topic they are trying to reference Shoap Technical Services Introduction Technical documentation is supposed to make technology accessible to the average person A good technical writer must translate difficult and sometimes arcane words into something a person can understand and more importantly use to operate a piece of machinery or software Everyone agrees technical documentation is necessary and important and when it is good people are generally happy The problem is it is rarely good Either it is too simplistic to be of much use or too technical to understand Why is this Let s examine some of the root causes Sometimes the problem is very simple users cannot find the topic related to the problem they re having The Table of Contents and Index the obvious first places to look are unhelpful The topic isn t listed in either location A search through a pdf file reveals nothing of substance or hundreds of citations equally useless for the person wanting a quick answer So the user
2. of audiences We are flexible so we can take on all of the documentation and training responsibilities for a company or work with an in house technical writing group to provide the support you need We are just as comfortable carrying a process through from start to finish as we are helping our clients start a project and then transitioning it back or finishing a project already in process We are here to support what you need For more information you can contact us at info shoap com or visit our website www shoap com Shoap Technical Services 7 What s Wrong with Technical Documentation References Curtis Anthony J Health Psychology New York Taylor and Francis Inc February 2000 Serving the American People Best Practices in Resolving Customer Complaints National Performance Review lt http govinfo liorary unt edu gt Shaw Charla L Markham Customer Satisfacftion Communication Training and the Help Desk Hot Line lt http www eric ed gov gt Vescio Thresa K Power and the Creation of Patronizing Enviornments Journal of Personality and Social Psychology Vol 88 April 2005 lt http www usernomics com documentation html gt Various manuals on file Shoap Technical Services 8
3. concepts Clearly a writer cannot inform the audience what something is unless the writer knows herself Whether or not this writer could indeed explain a Fibonacci Retracement the help guide implies not The omission of important details of a product annoys the reader and this anger is only amplified when explanations are so simple that they come off as patronizing A person who reads the help manual already feels confused and slightly vulnerable Repetitive or uselessly simple instructions come off as patronizing or just plain stupid Let s look at another example The other day was looking at documentation of a popular desktop device synchronization tool A box labeled Communication Port Selection had appeared asking me to specify a communications port The only explanation in the documentation about what to do was to specify a communications port and click next These instructions are simple enough to follow It doesn t answer the main question was asking though It is pretty easy to assume that you choose a port and click next to finish the process however it is not intuitive what each of the choices are and which you want to use What s Wrong with Technical Documentation Full time writers on staff or outsource needs For a more detailed analysis of the advantages and disadvantages of outsourcing or keeping documentation in house there is a section in our last whitepaper Why You Can t Afford Not t
4. ing a full time technical writing staff or if your needs are less overwhelming than is required of full time salaried staff hiring a technical writing consultancy firm Technical writing doesn t have to be bad it just has to be written by qualified individuals With the right writer companies can avoid gaps in documentation overly technical jargon and overly simplified prose and have happier customers While it means companies need to find writers with appropriate skill sets good technical documentation is not only possible but easily accomplished What s Wrong with Technical Documentation About Shoap Technical Services At Shoap Technical Services we work with you to quickly become a member of your team Our expertise in documentation and training preparation allows us to provide professional leadership for the team We are experts in creating documentation and customizing them to your needs We can demonstrate all of the documentation and training options available and then discuss the timeframes budget and requirements of the chosen project Our mission is to provide you with value added service on each and every project Our writers are extremely technical with degrees and backgrounds in computer science and engineering and our editors have advanced degrees in composition and communication We understand software and business processes and can translate technical concepts into easy to follow material for a variety
5. is unintentionally and unknowingly simplified This is usually the result of a well intentioned writer who doesn t have a clue what the technology is or how it works Such writers have the What s Wrong with Technical Documentation Patronizing environments lower performance Psychologists have found that when people feel that they are being patronized they not only become angry but that they perform worse on otherwise manageable tasks Shoap Technical Services mindset of just tell me the basics and l II write it don t need to understand how it works In doing so they go against a basic tenet of any good writing if you don t understand what you re writing about no one else will either The overly simplified information often leaves the reader lacking basic information For example one online stock management software s help guide has a list of all of the drawing tools and how to get to them using shortcuts However when you click on any of the functions to see what they do it defines them as a drawing tool to create charts that can be reached by whatever shortcut The person looking to the help guide to figure out what the Fibonacci Retracement tool actually does will Know as little after consulting the help file as they did before While there is nothing inherently wrong with the explanation it is too simple to be useful This type of documentation is the result of oversimplifying the
6. o Do Technical Documentation Shoap Technical Services in order to make the device work Leaving out details about what a communications port is and how it is used makes the process impossible to complete The documentation is too simple to be helpful The absence of important components of a product or the oversimplification of directions and definitions make for poor technical writing The reader comes away from reading the manual no more informed and much more annoyed The result is an unsatisfied and angry customer A Simple Solution Often these problems with technical writing could be avoided had the technical writer chosen for the project been both technical enough to understand the material and naive enough about the technology to make sure the material addresses the needs of the audience Technical writing is not written to be eloquent or pithy but rather to be concise easy to understand and straightforward The purpose of any piece of technical documentation is to inform the audience about the intricacies of a product or process without leaving out anything important such that the average user can easily understand what he is reading In order to achieve this result technical writers must be both technical enough to fully understand what they are working with and yet removed enough from the development of the product to be able to describe the learning curve they experienced This can be achieved by hir
7. s already frustrated because they cannot figure out what they re supposed to do get angry that the help file is no help at all or the User s Manual is certainly not for the average user Overly Technical Documentation Then there is the complaint that the material is too technical While overly technical documentation may sound like a contradiction in truth this is a very common problem When the level of the material is above the user s understanding of the product or technology the material is useless That s not to suggest that for certain audiences the writing can be overly technical documentation for software developers for example has to be technical It just means that the writer has to understand the intended audience and write to that level This problem most often occurs when developers of a product write the documentation It is difficult for the person who designed and built a product to understand what type of problems a novice user might experience For a person with intimate knowledge of a product or system to provide useful clear and concise information What s Wrong with Technical Documentation Psychologists warn against technical jargon Psychologists are advocating banning the use of technical jargon by doctors when trying to diagnose problems with their patients because they have noticed that using technical jargon above the level of the patient s comprehension breaks down comm
8. ten in an easily comprehensible way In either case though the customer ends up frustrated and the directions are of no use to anyone In many instances a technical person will use flow charts diagrams and jargon in an attempt to explain a product even though most users do not find such pedagogical methods very helpful What technical people often don t realize is that the use of unfamiliar jargon or of assumptions about product knowledge often comes off as patronizing This angers the user and does more harm than help solving the problem at hand This increases calls to the help line and often makes the callers disgruntled before the call even begins Overly Simple Documentation On the flip side some technical writing is too simplistic to help the reader In this case the documentation is easy to follow but what is written doesn t actually address the technical nature of the product After reading this type of material the readers are no more informed on the intricacies of the new technology than they were before Rather than simplifying the technology to a level that explains how it works in simple language the oversimplified documentation just leaves out the more complicated concepts or writes about them in a way that simply is not relevant Users who want to fully exploit the features of a new product will not be equipped to do so They will be hindered by the poor technical resource Most of the time documentation
9. understand printer jargon instinctively To the average user though this may not be readily apparent This makes the manual too technical for most These technical assumptions in the manual can be frustrating and they often cause an increase in annoyed customers Another instance of this can be found in instructions for installing a graphics card into a computer For this particular model only four lines of help are given to the new user The first line simply says to turn the computer off and open the case The user is then handed this confusing set of lines 2 Make sure AGP slot in M B and plug in card properly 3 Check the connector s type in VGA and properly connect to your monitor The final line offers no clarification but rather reminds the user to close the computer case and turn the monitor back on before using Since there is no accompanying diagram or picture instruction that makes What s Wrong with Technical Documentation Shoap Technical Services the process easier the user is left with a myriad of questions What is an AGP slot and how do you make sure it is in M B What is M B even How do you oroperly connect all of the many parts as instructed After some further exploration users may be able to figure out how to install the card on their own or they may call the manufacturer While this accomplishes the same goal the time and effort expended are much greater than if the instructions were writ
10. unication The patient can no longer answer questions gets frustrated and interactions double in length and stress If jargon is confusing in the doctor s office imagine how much more confusing it can be in other situations of stress Shoap Technical Services to someone less familiar with the product is if not impossible very difficult indeed A real life example While trying to print copies of a presentation the other day a colleague got an error message with a code to reference in the manual to solve the problem When he looked up the reference code on the screen the explanation read You have exceeded the duty cycle capacity of the machine The manual did not however explain what a duty cycle was or how to fix the printer when it was over capacity Upon calling the manufacturer he discovered that a duty cycle is how long a printer can operate before needing a rest Since the printer had been left on for the entire time he was trying to resolve the problem the printer did not have enough time to rest and copies could not be made in time for the presentation This problem could have been easily solved if the guide had defined a duty cycle and told the user to simply shut off the printer for a while to reset Instead the documentation used jargon unfamiliar to the average reader making it too technical to be helpful In this case the writer made a faulty assumption that a person using the printer should

Download Pdf Manuals

image

Related Search

Related Contents

  DT-ROBOT - Innovative Electronics  DPX-770MD 取扱説明書  Zelmer Aquos 829.5 SK  MZS-NPE取扱説明書 【PDF】  

Copyright © All rights reserved.
Failed to retrieve file