A few moments with Lesley Hays….
Among your many talents (development, shopping, hula hooping to name a few) you’re also responsible for writing a majority of resource manuals for clients and internal process guidelines for Bluewire Media staff. One might say that you are our unofficial technical writer…
Where do you begin when first writing a reference manual?
As with any writing, it helps to start with general information and gradually become more specific.
In the case of a reference manual, I’d start with basic contact information for support, log in details, and an overview of the system to provide the user with a very basic starting point. Then start going into more detail, first about the consistent areas of the system (global navigation, common buttons etc.) and secondly, about really specific parts relevant only to that particular client.
Do you find it difficult explaining technical information to the lay person?
It can be hard, as simply replacing jargon with regular words doesn’t necessarily work. Sometimes the concept itself can be quite foreign making it very tricky to communicate even if using 10 year old English.
To illustrate, compare two explanations of a WYSIWYG editor:
Example 1
A WYSIWYG editor is a content editor that allows you to edit text, images etc and have them look how they will in the final context.Example 2
A WYSIWYG editor allows you to update content on your website using tools similar to the basic functions of Microsoft Word. This means that you can see what the finished product will look like on the website before you hit save (and also you don’t need to know any code!).
How do you overcome this?
One of my favourite techniques is the analogy, which can help explain not just how something works but also why things happen. If you get an analogy wrong, though, it can make things even more complicated!
During your time at Bluewire Media how have your methods of writing improved /changed?
I’ve had lots of opportunities to get feedback from both colleagues and clients over the past couple of years, which has helped me discover what concepts and words the general public needs explained. It’s also helped me write instructions more clearly and even change my tack on reference manuals completely…
In what way have your made help information more accessible to clients?
The majority of the manuals I write are for content management systems. In the last few months, I’ve been experimenting with embedding the help information I write into the administration area of the system itself. This means that when a client has a problem entering content or editing something, the help information relevant to that part of the site is just a click away. So far, feedback on this technique has been positive.
How is writing a process for staff different from writing a reference guide for clients?
The main difference is the amount of background information required. Staff processes don’t need lengthy explanations or glossaries – they just launch straight into the meat of the document. I expect that the staff I am writing the process for already have the technical background necessary to understand the process.
How do you decide what processes need to be written?
Deciding what processes need writing is possibly more difficult than actually writing them! I’ve recently been doing just this for our development processes and I found the easiest way was to write a really general overview of our entire development process, then decide what parts of the process needed further explanation. I’ve created a list of required processes and am slowly making my way through them – I’m sure the list will change and/or grow as I write more.
Why go to the trouble of writing processes down? Can’t information be passed on verbally?
There’s nothing worse than wondering how to do something and thinking “I bet John Smith would have known…” if John left the company 3 months ago. Writing down processes regularly and thoroughly means that the company isn’t reliant on any one person – which lets them withstand sudden resignations or fast-tracked inductions far better.
Everything used to be passed on orally hundreds of years ago… then we invented the printing press. Now we have computers, so why look back?
I understand that you will be expanding on your technical writing skills next year. What areas of your writing do you hope to improve upon?
I’m planning on taking a technical writing course. The course focuses on communication around technical issues in general, so it’ll be useful for everything from internal processes, blog articles, help manuals and even everyday emails to clients.
Make sure you let us know how the course goes!
