Ethos Community

Did you notice something when you bought your new techy gadget? You open the brand new box and with it comes a hard copy manual. You find it very useful because you are excited with your purchase and want to know how to use your new tablet or electronic device. After the first use of that paper manual, you file it away and it rarely gets used and you can't find it either.

But when you get stuck again, you simply click on Help and read the electronic manual inside the device or go to the manufacturer's website to read the manual. But wait, there is more. The website provides PDF documents, video clips or the help documents are interactive, dynamic and full of embedded images and hyperlinks to take you to many other sources of information.

Recently I won a Technical Writing contract. My job was to write a new manual for a home alarm system. The old analogue system uses the conventional keypad that you press to enter your code to set the alarm. But now the same system uses a new user interface which is a tablet. The tablet software is more sophisticated, visual and user friendly. Anyone who uses a smartphone can use the alarm tablet to configure and set the alarm and do so much more.

My challenge was to create a document that enables the user to quickly learn how to use the alarm system. Basically to make it idiot-proof and in plain and simple English.

So I devised a cunning plan as I was also new to this alarm system. I wrote down every step I took to learn the various functions and features available in the system. I made a few mistakes along the way and set off the alarm or it did not do what I wanted. I tried again and again until I got it working. I then amended my document.

I took a screenshot at each step and then wrote down the Step-by-Step instructions. I then tested the document against the system a few more times. It worked!

Then I spellchecked, formatted and proof-read the entire document. A third party also reviewed the document and the sponsor gave me the thumbs up. I got paid.

I know that the end-users all around the world will be using my user manual to operate their home alarm system. There is no HELP button on it to call me for any further help.

I have suggested to my sponsor how this could be enhanced further by using interactive authoring and publishing tools such as Captivate 8.

The basic principle still is: You learn first, then show and tell others in their language and they will learn and remember long after you are gone.

Is this how you would write a Technical Document? Any better ideas or tools?

Views: 129

Add a Comment

You need to be a member of Ethos Community to add comments!

Join Ethos Community

Comment by Hazel Owen on June 5, 2014 at 19:49

Thanks for getting back to me with such in-depth responses, Adon.

The 50 hours it took you to write (excluding your own learning time), I feel, indicates just how much is involved in developing really useful guides! The FAQ resource you linked to, also illustrates one of the multiple ways in which users interact with both the device or thing they are trying to use, and the help / guide resources that come with the device. A real challenge...and a real skill!! :-)

Comment by Adon Kumar on June 3, 2014 at 15:46

Thanks Hazel for your comments. Good to hear about your first pre-interview task. You asked me a few questions, so let me respond.

I was asked to create the User manual in MS Word but I did have to use some advanced MS Word features such as Figures, TOC, Glossary etc. My document would be also converted to PDF for downloading and be part of the Tablet software.

No, it wasn't all text. I had many screenshots which I resized as smaller images and used them as numbered Figures within the manual. I also enhanced the screenshots by putting arrows to explain various parts of the screen. I created a number of my own diagrams as well to explain the basic features of a tablet e.g. touch, hold, how to use your fingers to zoom in, zoom out etc.

The Alarm System has lots of functions, so it took me around 50 hours to write the document (excluding my own learning time).It enjoyed the challenge and the learning experience.

Many websites also require FAQs which function as an online User manual. I have created my own FAQ for one of my RFID Animal Tracking Software if anyone wants to have a look at

Comment by Hazel Owen on June 3, 2014 at 14:18

An interesting process, Adon. When I first graduated (having completed a degree in Literary Studies and Linguistics), I went for a job as a technical writer. The pre-interview task was, I remember vividly, to write instructions on how to make a cup of tea for aliens who had newly arrived on the planet Earth, and who had no clue what 'a cup of tea' was. I think I may have been rather literal, and ended up writing a mini-epic on what tea was, what elements comprised water, and some of the physics around boiling water!! ;-p Needless to say, I didn't get the job. However, I did learn something. Writing simply and clearly is a real is figuring out what people need to do to complete a task successfully...but without me making unfounded assumptions about what a potential user may or may not know. It's really tough as people will have a range of learning needs, and a variety of background knowledge. Also, some will prefer diagrams and demonstrations, whereas others will want to read the text...and so on.

From an end-user point of view I have frequently read descriptions or 'how to' guides where an essential step that seems obvious to the writer has been missed, leaving me with steam coming out of my ears! 

So, it sounds as though your process, as a new user, of figuring out the steps and then refining them to make sure nothing was missed, is one that will help avoid the missing steps. I guess, time and resources allowing, asking another couple of users to follow the document to see if there are hiccups, would help with the robustness of guide. Can I ask - how long did it take you to complete the process? Was it a purely text-based document, or did you have leeway to also include diagrams? And, what do you feel was your number one takeaway from the whole experience? :-)

Since my first attempt at technical writing, I have written and/or designed a number of 'how to' guides and demonstrations. One of the key luxuries I have had is, once the guide has been created, observing how a wide range of users interact with the guide, and this has enabled me to spot where the 'holes' are. I then tweak and add things over time. Also, in line with your suggestion to your sponsor that the guide could be enhanced further by using interactive authoring, I also try to ensure that: 1) I create a range of guides assuming that users are coming in with a variety of experience, 2) with a linked glossary, and 3) I create / use a number of different media (diagrams, animation, videos, and audio for example). It makes for a big initial investment...and when something changes some of the media is tricky to update...but, it has meant that users are able to find what they need to help them, when they need it.

As a point of general interest, I found a couple of resources that dip into technical writing:

© 2019   Created by Hazel Owen.   Powered by

Badges  |  Report an Issue  |  Terms of Service