Writing a Technical Manual? – some tips from the specialists

September 13th, 2010

If your company manufactures a product that your customers or agents need to know how to install, operate or maintain, whether it’s a combine harvester or a software application, you need to provide them with the correct information, in the form of a manual or user guide. If you don’t do it well, you’ll get unnecessary enquiries to your helpline or customer support department and dissatisfied customers who might not come back. This article discusses some of the points to consider.

What is it for?

You need to have a clear idea of the purpose of the manual, in order to ensure that you include everything the reader needs to know but do not include superfluous and potentially confusing information.

Who is it for?

It’s crucial to know the audience. What assumptions can you make about the reader’s existing knowledge of the subject and related technology; for example, if the manual is to describe the installation of a gas detector to an existing smoke detection system, will the reader be well-informed on smoke detection, but new to gas detection? Sometimes, the audience can be very well defined, such as military personnel. At the other end of the spectrum, the audience could be members of the general public and therefore vary considerably in their existing knowledge.

How will it be distributed?

Will you be producing small number of printed copies for internal or agent’s use, bulk printing for shipping with a product, or publishing on line? These decisions affect both the production tools you should use and the design of the document.

If you are going to laser print a small number of copies, a word processing application, with its many powerful text manipulation and automation tools, is probably best. If you intend to use a commercial printer, they are not keen on word processor output, so you will need to consider a page composition application.

Ideally, on-line documents should have a format compatible with a computer screen, so that scrolling is avoided, and should take advantage of the ability to link references within the document. If you intend to distribute in both printed and on-line form, you may have to compromise.

Will it be translated?

If you anticipate a need to translate from English into one or more foreign languages, be aware that they generally take up more space, as much as around 30%, in the case of German and most Scandinavian languages. Incidentally, perhaps surprisingly, simplified Chinese characters take up about the same space as English.

It is advisable to maintain a one-to-one relationship between pages in all languages used, to assist in responding to queries and making updates. You will therefore need to allow sufficient additional space on each page, or adjust font sizes, to accommodate other languages.

Who is going to create it?

What about knowledge of the subject matter – presumably the person who knows the subject matter best, such as the designer, is the obvious choice? In fact, this is probably not so, because they are likely to overlook what to them is obvious, but to the reader requires explanation. The author needs to be someone with an appropriate technical background but who will ask those questions that the reader might.

You may also need to make use of specialists, such as a technical illustrator.

The process

Having made all those decisions, it’s time to get started. You’ll need to design not only the format but also the content, in the form of a structure of headings. If you expect to use a lot of cross-referencing, it’s best to use numbered headings. It’s important to employ best practice by using the features of the application, such as styles and automatic numbering, cross-referencing and contents lists, to ensure accuracy, ease of updating and consistency. You need to be consistent in the writing too, so that the same item or function is always referred to by the same term. Consider the readership and purpose of the manual as you write and review what you have written. If at all possible, get somebody independent not only to proof read it, but also to validate it against the product – your customer should not be the guinea pig!

An alternative to classroom training

August 25th, 2010

Computer-Based Training

As its name suggests, Computer-Based Training (CBT) is the provision of training using a computer. If you’ve never experienced it, or have suffered a bad example of it, you might conclude that it’s used, rather as someone explained why they climbed a mountain, “because it’s there”. That would be a pity, because it offers many benefits, which are introduced here.

Distance Learning

Click and Learn

Click and Learn

Clearly a computer is an ideal means of providing distance learning, or distance education, where students do not have to be physically at an educational establishment, or in a classroom. Although the training material could be distributed by CD-ROM or DVD, almost ubiquitous Internet and intranet access allows it to be made available on line, subject to bandwidth considerations for some material. Distance learning has become a well-established and recognised approach to education, with courses to degree level. Computers are playing a big role in this, offering both synchronous learning, where students attend a collaborative virtual classroom with a teacher/trainer according to a specified schedule, and asynchronous learning, where students access the material at their own pace.

Self-Paced Learning

Asynchronous learning may also be described as “self-paced learning”, in that it allows the pace at which students progress through a course to be determined by their ability and existing knowledge and experience, as well as their availability. At its simplest, this pacing can result simply from the student accessing the material when they are available, or when they feel able to move on in the course. However, this approach fails to take advantage of the interactivity and functionality that a computer application can provide. A computer-based course can include branches, which a student can choose to follow in order to learn more detail about a particular item, according to their existing knowledge; this knowledge can be tested at that point, resulting in a recommendation to follow a branch, or indeed to force that route, if a question is not answered correctly. Similarly, progression through the course can be dependent upon correctly answering questions at certain stages. This process need not be open-ended and can be subject to quite rigorous controls.

This mention of asking questions of the student introduces two other aspects of CBT: reinforcement and assessment. Although the two can be combined, it is not our preferred approach and I will discuss them individually.

Reinforcement

Sometimes, it can be beneficial to describe something in two alternative ways, in order to reinforce a particular piece of information, or a concept. We prefer an approach whereby, after introducing a subject, the course will include a quiz of one, or a short number of questions, to test a student’s assimilation of the subject. When they answer correctly, they are allowed to move on, probably to the accompaniment of a congratulatory reinforcing statement; if they answer incorrectly, they can be offered another chance, accompanied by a hint (“have you thought about…?”), which also reinforces the learning process. We would not normally regard such quizzes as part of any formal assessment.

Assessment

Students can be assessed for assimilation of the material by presenting them with one or more tests, each comprising a number of questions, perhaps at the end of each module. The questions would usually carry scores, which can be weighted according to their significance, so that each test results in an individual module score and these can be aggregated into an overall course score. Progression from one module to the next can be conditional upon achieving a predetermined pass mark and full completion of the course upon aggregating an overall pass mark; this can lead to the on-line award of a certificate, which can carry a unique randomly-generated authentication code.

Whether the questions are for reinforcement or assessment, varying degrees of randomisation can be introduced. Although completely free text answers are notoriously difficult to manage reliably, there is much scope to extend beyond simple multiple choice and we have developed means of introducing students’ own entered data into the course, resulting in answers unique to themselves, without jeopardising reliable assessment.

Rich Content

What of the content? I have seen many examples of CBT where the content is little more than an on-line version of documents and presentation slides that could equally have been sent through the post, admittedly at greater expense and impact on the environment. This is such a waste of the power of the computer. I have touched upon the interactivity that can be included in terms of branching, but this can be extended, for example, to selecting specific items of information (from text to other media) to view from a screen, to give an extra bit of involvement. The different media types available through a computer, such as animation, software simulation & demonstration, video and audio, together with the underlying ability to manipulate student-entered or other data, can all add to the learning experience and assist in assimilation of the essential content.

Learning Management Systems

We are able to manage course enrolment, access periods, progress, assessment, certification and communication through our Learning Management System (LMS), both for our clients and, quite recently, to the public, with payment facilities. The LMS The i-Team has adopted is Moodle, which is used by many academic institutions worldwide. If your company has an LMS and you need to know if our courses can be SCORM or AICC compliant, the answer is “yes”. Assessment can be independent of an on-line course and provided via our (or your) LMS, in order to evaluate students who have participated in classroom training; this can be controlled to minimise the opportunity for unwanted collusion.