Imagine you are an IT manager for an organisation that has been implementing new IT systems. You have now reached the point where you need to create and document the new IT policies and procedures. The organisation already has some general policies for IT in its staff handbook, but you need to provide more detailed information on how to use the organisation’s IT efficiently and securely.
For example, the staff handbook tells staff that customer information must be treated confidentially and only approved communication channels must used. The IT policy and procedures document will provide more detail – that web email services (such as Yahoo Mail) must not be used to send customer information, because they often store a copy of the email even if you have deleted your sent message.
The best approach would be to have some sections in both the staff handbook and the IT policy document. In other words, the same content in different documents. Otherwise, staff would need to have two manuals open each time they wanted to check they were doing things correctly.
If you use Word, you’re likely to do this by coping the text from one Word document and pasting it into the other Word document. The problem with this approach is that when you make a change to the text, you need to remember to paste any amended sections into the other document. This make it very difficult to create customised variations of documents, such as cut down versions for managers or new staff, branch-specific versions etc. It becomes unmanageable.
One of the benefits of using some of the alternatives to Word is you can embed a piece of information into multiple documents. In a similar way to how you can use the same image in lots of different web pages, you can use the same chunk of text in lots of different documents. The advantage of this approach is that in the future you’ll only need to change the source, embedded chunk of text when it’s time to make a revision. That piece of text gets updated automatically (or semi-automatically) in all the documents that use it.
Many software companies, when they start out, provide user documentation as downloadable PDFs or as web pages. As they develop more products and versions, and as they expand into countries that use different English spellings, the amount of documents can grow until it becomes hard to keep all of these documents up to date.
It’s at this point that they tend to call a specialist technical writing company (such as Cherryleaf) to see if they can fix the problem for them. We find they’ve usually had a brief look at a Help Authoring tool, such as Flare or RoboHelp, and can see that it would solve a lot of their problems. However, they’re often not really sure how to use these tools in the best way.
Although topic-based authoring has been around for over twenty years, for many people it’s a completely new concept. It is, to quote from either Hamlet or Star Trek VI, an undiscovered country. Our meetings with them often end up focusing on the benefits of topic-based authoring.
Topic-based writing is an approach where you write a piece of text (or topics) that typically contains a paragraph or two about a single topic. These topics can be combined to create a page in a PDF document, and they can be organised in a sequence to create an online Help system ( See topic-based authoring page in Wikipedia). It’s a modular approach to creating content. The main advantage of this approach is the topics are often reusable; you can save time by reusing topics across different documents, and you can publish the same content to different media. For example, you could use a topic in training courseware, in a user guide and in marketing information.
As each topic is usually about a specific subject, and has an identifiable purpose, it can also help the writer write more clearly. If you need longer articles, you can build these up from the topics you’ve created.
It’s easy for professional Technical Authors to forget sometimes that many people have never come across this approach to writing before.
Through its Listener Scheme in prisons, Samaritans provides emotional support to prisoners who are struggling to cope, are self harming or are feeling suicidal.
Guidance for Samaritans volunteers that run and support Listener schemes was contained in a hard copy manual (the Guide to Prisons) which was cumbersome to update, difficult to navigate and not in a format that made it easy to share with prison staff. As a result, over the years, volunteers referred to it less and less frequently meaning that consistency in delivery of the Listener scheme across the prison estate was being compromised.
Cherryleaf were tasked with converting the manual to a fully searchable, easy to use, online resource that would link to other relevant information on the Samaritans intranet and could also be made available on the Prison Service intranet. The new online Guide to the Listener scheme means that both Samaritans volunteers and prison staff have access to the same, up to date, comprehensive set of guidelines and information.
Maria Foster, Samaritans’ Prison Support Officer said:
“For Samaritans volunteers, having the information available on the intranet rather than in a manual in their branches, means they can find out what they need to know at any time; the search facility and page style ensures that information can be located and read quickly and easily.
For prison staff, this is the first time they will be able to see all of the Samaritans guidelines for running the Listener scheme; this will help to further develop their understanding of the scheme and will support them in facilitating the operation of the scheme in their prison.
Samaritans is delighted with the result of the project;
Cherryleaf understood the brief and very quickly got to grips with the subject matter, turning a cumbersome manual into a streamlined user friendly resource.”
The Samaritans provides confidential emotional support for people who are experiencing feelings of distress, despair or suicidal thoughts. You can talk to them, any time, on 08457 909090 (UK), 1850 60 90 90 (Republic of Ireland) or email@example.com .
The Wallace Collection recently held an exhibition on The Noble Art of the Sword, where visitors could see range of beautiful fencing manuals written during the Renaissance.
So could a Technical Author learn anything from the way historical fighting manuals were written? I have practiced aikido, a Japanese martial art, since 1992, so the thoughts below relate to the instruction manuals developed for aikido. In particular, the first aikido manual, Budu Renshu.
The writers. The instructions were not primarily written by the founder. Instead they were written by a student (or students), with the copy reviewed and approved by the Head of aikido. Perhaps the task of drawing the diagrams and writing the text was given to someone who had skills in drawing and writing instructions. The Head focused more on writing the chapters that explain the values and philosophy behind the art.
The purpose of the manuals. The purpose of the manuals was as a memory aid, not as a self-study guide. In the same way that you cannot learn how to ride a bike by reading a book, they were not designed as a replacement for practice time on the mat.
The audience. The instruction manuals were not written for beginners or for the general public. They were written for intermediate and advanced students.
The information design. The pages contained step-by-step images, with explanatory text below. Simple line drawings are used, to make the information more understandable. Some expertise is needed to understand the techniques, as 2D images were used to explain three dimensional movements. Sometimes, the diagrams change to a different perspective, which makes comprehension harder for the reader. Later aikido manuals added lines and arrows to indicate the direction of movement. One of these books, containing diagrams by professional illustrator Oscar Ratti, is still very popular today.
The accuracy of the documents.The text-based instructions below the images in Budu Renshu have been useful in spotting errors in the diagrams. The manual was copied by students using tracing paper, and sometimes a mirror image was drawn by mistake.
It would be great to find out from someone involved in reviving the Renaissance sword fighting techniques if there are similar features in the manuals of Alferi, Rapisardi and others. Please let us know.
Samaritans is a charity that provides confidential emotional support 24/7 to those experiencing despair, distress or suicidal feelings. The service is provided by over 20,000 volunteers from 202 branches.
The Samaritans Operations Manual explains in detail the policies and processes which volunteers must follow when delivering the service. This new online manual will replace four paper manuals and will be accessible in every branch by every volunteer. Cherryleaf has provided conversion and editing services so that Samaritans can make the manual available online through its intranet.
“The Samaritans Operations Manual will be one of the most important resources volunteers use to support them to deliver our service. For the first time, all the information they need will be in one place. This will make it so much easier for volunteers to find what they need quickly.”
The manual will be written in such a way that volunteers can skim through it, or read every detail. It will be stored on the Samaritans intranet and be fully searchable. It is written in plain English and version-controlled, so it will be always up-to-date.
The new Operations Manual has been uploaded onto the Samaritans intranet, and has been reviewed by Regional Officers and the Quality and Visitors group. It is now being reviewed by the branches prior to its official launch later this year.
The Samaritans are also in discussions with Cherryleaf about turning other manuals into online resources.
When reviewing an organisation’s procedures documents, there are a number of key factors we look at. These relate to the value of the document itself, how it is structured and the clarity of the content (i.e. the words and sentences).
One way to rate these factors is by a simple red, amber, green traffic light system. Using this approach means the key areas of concern can be highlighted to everyone involved in the project. Red indicates an area of high concern, amber indicates medium concern and green indicates no change is needed. Here is an example below:
How do you assess organisational operations and procedures documents?
Here is a very innovative approach to providing a user guide, from Samsung :
According to Vitamin Design:
These books actually contain the phone. Each page reveals the elements of the phone in the right order, helping the user to set up the sim card, the battery and even slide the case onto the phone. The second book is the main manual – the phone actually slots into this and becomes the center of attention. Arrows point to the exact locations the user should press, avoiding confusion and eliminating the feeling of being lost in a menu.
It’s a interesting example of user documentation as an emotional experience. (Thanks to Gareth Williams and Adam Wohl for spotting this.)
Yet another sign that quick reference cards are back in fashion:
Plans to be set out in the Families Green Paper will propose better advice and information for couples and address the balance between work and childcare by considering ways to make public services more “family friendly”.
Under the Green Paper, new fathers will be given a manual to help them adjust to the role.
The “dads’ guide”, put together by the Fatherhood Institute, will include an explanation of breastfeeding and tips on how to support their partner. (Source: BBC News)
The ‘Dads’ Guide To…’ cards are A6 sized quick reference cards printed on both sides with important messages for dads and male carers about their child’s development and how they can get more involved in their child’s life and learning.
Sadly, one question asked by many new fathers remains still unanswered: where do you take the baby’s batteries out?