I am sure you might also have faced a situation, where the instruction in the manual misled you or did not help you much. If you are writing a help manual or a tutorial for a product, it is very important that you write precise instructions.
Most people think writing precise instructions means writing less words and writing simple grammatical sentences with the right choice of words. When I say precise, I am not just talking about the language or choice of words. By precision, I also mean accurately listing the logical steps to work with the features in the product.
The purpose of any help manual gets served, only if the user successfully uses the product just by following the instructions in the manual and when the user does not feel the need to call for any external support.
If you want to write precise instructions, here are some things you must keep in mind while writing:
- Think in terms of the user all the time
- Never assume that the user might know some step because it is obvious
- Never assume that any step is trivial and needs no mention
- Make sure someone else executes your instructions and checks if the steps are correct and useful
If you faced a funny situation while trying to follow a instruction manual, please share your experience by writing about it in the comments section. 
Personally I’ve never found help manuals useful when ur in trouble and trying to resolve a real time issue.
I usually resort to the internet, asking a developer or just Rnd myself. Takes longer but you will certainly reach a resolution this way and not referring a manual. I even have feedback that developers never resort to referring to a manual for similar reasons.
Sreya,
I agree most help manuals are not very useful.
However I would like to mention NetBeans documentation: http://www.netbeans.org/kb/index.html
This documentation really helped me learn about business processes, web services and so many other technology related stuff. It would not have been possible for me to ask someone and learn all this.
I guess well written help manuals really turn out to be useful and help you learn things the product on your own.
Thanks for sharing that Rupa. The reason I chose to mention this is issue because more often than never, manuals are written keeping the most normal situation in mind. The writer does not have the knowledge of the real time issues that crop up in production. Everything is written linearly assuming nothing will go wrong. But this is seldom true. Most often when a product goes into production, there are a number of events that occur. There are so many roles involved in installing, administering and using a single product. The other thing i don’t see being thoroughly done in technical writing is the audience analysis. TW requires a detailed audience analysis to be done so a writer can imagine the job role of the audience and write from that perspective.
Manuals also tend to be less task based and only from a perspective of how to use some feature. It misses the connections between the features quite often. Manuals need to prepare the user for every thing they may encounter from Install to using the product. I feel a lot of research needs to be done and the TW should be able to use the product themselves, run into the real problems that a user will, and then write the documents. That would be the real value a manual can bring.
Manuals need to address problems more that ideal situations.
Just my thoughts… and thanks for bringing up this topic.
Sreya
[...] This post was mentioned on Twitter by Rupa Rajagopalan ande-Learning Audio. e-Learning Audio said: RT: Writing Instructions is All About Precision! : by ruparajgo | Create your own Cartoon at http://www.toondoo.. http://bit.ly/1Ij1L [...]
Awesome thoughts Sreya. I completely agree with you on this.
This why I believe in end to end tutorials for software products. In such tutorials, you can capture some real life scenarios.
Instead of simply listing instructions in the manual, the technical
writers might also give ample real life examples to explain concepts.
A manual with lot of examples/scenarios is sure to become a hit.
Ok.. Devil’s advocate speaking here – Writing instructions means that the learner requires instructions…
Life doesn’t come with operating instructions… then why do our products require them? are they not intuitive? are they not robust to withstand a few errors? are they not required? (I don’t need to understand hence I wont)
Maybe… JUST maybe, the design itself requires tweaking…? an effective design should require very little ‘instruction’
Sure… does that mean you and I will be able to handle the petroleum refinery plant without instructions..? Of course we will not be able to… but we aren’t the learners… there is a separate batch of people whose job it is to… and any tool THEY use should be intuitive to THEM…
I am not being bitter here – but think of it… don’t you think design should be usable…? without instructions?
Guidance perhaps is required in some places… and maybe some nuances, best practices and stuff too… but not INSTRUCTIONS perse… Hell I dont know quite a few shortcuts in MS-Word… but I didnt require ‘instruction’ to learn it… i required an interest… the ability to randomly try out stuff without managing to bring down the system (though I am sure we all have managed to bring down a few systems in our time), and perhaps somebody to prod me along… a lot of things… but not instruction…
I am not claiming the MS-Word is great design… but it is definitely usable… and successful… and it is a great TOOL… it does not make me a better writer – but it helps me write well. It is thus good design.
So… coming back to writing instructions…
For a more traditional POV… writing instructions should pass through a few filters:
Is it accurate? (correctness)
Is it adequate? (completeness)
Is it appropriate? (usability)
Is it articulate? (understandable)
I guess if these (top of the mind) filters are followed – then what is written is indeed ‘precise’…
Any other filters you guys can think of?
Good points Abhinava… I just wish that our tools are intuitive and need no help manuals. Unfortunately this is not the case. I agree if you have interest, you need no instructions and you explore and learn.
But there are complex tools, which scare you to death. You simply feel lost and have no clue what to do with it, though you know it can solve your problem. For such complex tools or applications which are highly technical, step by step instructions do help a lot. I am speaking from experience