Sample introduction of user manual

Typical problems might include: installing the product, using the product, using the product safely, maintaining the product and disposing of the product. I asked Philip to identify the problems and solutions that his user might encounter during the product lifecycle. In order to do so, I created another template for Philip. Our user manual templates are compliant with this standard. Action: Use this template and the instructions on the first tab to identify the problems your user might have during the lifecycle of your product and present their solutions.

Philip has now identified the problems a user might have with his product during its lifecycle and he has now thought of the solution to solve the problem. In other words: Philip has defined the topics for his user manual. Each topic can only be about one specific subject, has an identifiable purpose, and must be able to stand alone. A user wants to solve one problem at a time. A topic will become a section in the user manual. It can be a chapter or a sub- paragraph.

As soon as a user is looking for an answer to his problem, he will use the table of contents to find out how to navigate to that answer. I asked Philip to structure the topics and define their place in the user manual, by assigning a certain topic to a specific chapter or sub- paragraph. You have now created the Table of Contents ToC. The ToC is the outline of your user manual. Each topic in the user manual gets its own heading.

The headings are the sub- titles that precede the actual text. They appear in the ToC, so the user can navigate to the needed information. Because the ToC entries play such an important role in helping your user find their way, and to help them skip what is NOT important, they need a bit more attention. Basically, you should try and work with three levels of headings: first-, second- and third-level headings.

The first-level heading describes what the entire chapter or section is about e. A third-level heading uses noun-phrases e. Packaging contents and Tools to be used. Meaningful Headings tab. Dependent on the market where your product is placed in or put into service, and dependent on the product group your product belongs to, specific legislation applies to your product. These requirements also include requirements on the content of your user manual and safety instructions. In order to sell your product in a specific market, you should make sure that your user manual complies with these requirements.

These two articles below will tell you how you can find out exactly which legislation applies to your product for the European and U. Pro tip: when there is a Declaration of Conformity available already, you can find the applicable directives in there. Philip didn't need to conduct these steps, as the template he used already contained the legal content as required by the relevant directives.

For his product, it means that the following information is required for the user manual for his product:. This standard has been harmonised in the EU. Compliance with harmonised standards provides a presumption of conformity with the corresponding legislation! I have also created an IEC checklist that can be used to double check that your user manual complies with this standard. In order to create an internationally compliant user manual, you should always make sure your manual meets the EU, US and requirements.

I asked him to adjust the table of contents of the template according to his own table of contents. Without removing and mandatory elements of course Do you remember from step 4 that I asked to start the numbering of the sections with chapter 4?

Once you download the user manual template doc yourself, you will see that a few standard chapters have been added, as well as some appendices.

The purpose of your product, or better: the intended use, is the heart of a user manual and forms the basis of ensuring the safe and healthy use of the product.

The way the intended use is described also determines your liability and affects the further contents of the user manual. The most legislation requires you to include a description of the intended use in the user instructions.

The international standard for user instructions, the IEC , provides the following definition for the intended use:. An exhaustive range of functions or foreseen applications defined and designed by the supplier of the product. By describing the intended use you determine the safe envelope of the product. And once you have determined the intended use, you can focus on providing only those safety and user instructions for how to use the product within the given envelope.

Additionally, to the intended use, many more standards, directives and regulations also require you to include a description of the reasonably foreseeable misuse. For example, the reasonably foreseeable misuse of an aggressive detergent could be the use of it in a food processing environment. Paying too little attention to describing the reasonably foreseeable misuse will affect a company's liability. If the defectiveness of a product needs to be determined, all circumstances will be taken into account.

That includes the reasonably foreseeable use of the product. The description of the intended use determines which instructions are given in the rest of the manual. For example, if a cooling system is only used for cooling certain medications, then only these procedures need to be described. When it could reasonably be foreseen that the cooling system may be used as a system to cool organs, this should be described in the instructions.

By doing so, you, as the manufacturer, will limit your liability and you can focus on only describing how to use the system to cool medicines. Figure 1. Reasonably foreseeable misuse? Even though the intended use has now been clearly defined, this does not mean that using a product is completely without any risks. To identify the hazards that come with the use of a product, you can conduct a risk analysis.

A risk analysis can also be mandatory for certain product groups, such as low-voltage equipment, toys, machinery and equipment for use in explosive atmospheres. Standards, like the ISO , have been developed on how to conduct a risk analysis.

According to this method, there is the following hierarchy of risk-reducing measures:. This means that the user guide should warn of any residual risks related to the use of the product. This is done with safety warnings. A good safety warning describes the nature of a hazardous situation, the consequences of not avoiding a hazardous situation and the method s for avoiding it. Rotating parts. Risk of serious injuries. The first thing you may want to do on your way to provide users with the right content is to get to know both the subject and user better.

Do not assume the user has prior experience or product knowledge before you have defined who your user actually is. Dutch Rail NS were at a point where they considered converting all their existing paper user manuals available about their trains to online documentation and videos.

Playing a video usually requires high speed internet. Although reception is quite good in the Netherlands, high speed internet is not always assured when crossing the Dutch countryside. Also, when a train would have a breakdown in a tunnel, chances are big there is no internet and thus no access to information at all.

This made them decide to make all information available electronically, but in an offline format. By asking the correct questions that help you to identify who the reader is and where and how information will be consumed, you will be able to better serve their information needs.

Also, do not forget to consider the needs of disabled users. There might be users with low vision or who are colour-blind. You may want to serve them with alternative instruction manuals in Braille, large print or audio. As I am a big fan of visualising things, I encourage people to create personas. A persona is a visually presented user profile in which some reasonable assumptions are made about the characteristics of your users.

I learned about creating personas during my Master Industrial Design Engineering course. So, creating personas is not only useful when developing your user guides, but also at the start of the development of any product or software. These instructions are intended for the end-user of the [machinery name].

The end-user can be described as each person who interacts directly with the machinery. The end-user typically includes, but is not limited to:. All use of the machinery shall only be carried out by an authorized, properly qualified and skilled person of 18 years or older, who:. Exceptions to this are the supplied lifting and climbing materials and personal protective equipment.

The purpose of this document is to make the end-user familiar with the installation, use and maintenance of the machinery. Gaining knowledge about your users helps you to focus on what is important to them.

A commonly seen mistake is that user manuals often include marketing or sales information. This distracts the user from finding the information they actually need. Users usually consult the instruction manual because they want to get something done or solve a problem they are facing: They want to install the latest version of their anti-virus software, bake bread or find the meaning of the flashing warning light on top of their machinery.

Knowing your user helps you to write more consistently. It helps you select the correct information and to focus on the tasks that your user wants to complete.

This may seem like common sense, but knowledge really is the key to writing instructions that really help your users. For example, when writing the user instructions for a camera, knowing how the shutter speed and aperture interact with each other, makes it much easier for you to describe each function as it relates to the whole.

It is the task of the technical communicator to share technical information clearly with the user of a product. Technical education, background, experience and communication skills will help each technical communicator do this successfully. The best way to do this is by using the product yourself: try to install it, push the buttons, open lids, identify signals etc. Always take your own safety into account!

Possibly there is already some information available, such as existing instruction manuals, a risk analysis or marketing information. Study this information and go through the full product life cycle, from purchasing to disposal, in your head.

A hands-on approach trying the product yourself , will give you a feel for what sort of information needs to be communicated to the user.

When things are unclear, look for information on the internet or in existing, similar user manuals. Other product manuals can show you how other technical writers have found solutions for similar problems. But be careful…. Be critical and only consider information that you fully understand and can validate.

Also, existing material might not always be as clear. Often you find a lack of structure, inconsistency or vague instructions. We will discuss that later.

Your product may or may not include all the functions that you find in existing material. Identify the differences. What makes your product unique? What functions are identical? What information can you use for a better understanding of your own product?

When you slowly build up a complete picture of your own product, questions will arise. Not everything will be clear after your research. Make sure to note down any unclarities. These will be solved in the next stage. The best way to have your questions answered is by talking to knowledgeable people that know the product best. We call them subject-matter experts SMEs.

An SME is a person with a deep understanding of a particular domain which can be a job or topic. SMEs can be mechanical, industrial design, software or electrical engineers. They can be helpdesk support staff, maintenance personnel or installers. But also managers, scientific researchers, testers, dealers or business owners might have the in-depth knowledge of the subject that you are writing about and be the subject-matter expert you are looking for.

Make sure to do your homework well. Study your topic thoroughly and prepare a list of clear questions. Gather all your questions together and make an appointment. As SMEs are valuable to a company because of their knowledge. They are also busy people. Take this into account when you are interviewing them. Most technical SMEs are more comfortable in the world of numbers, processes and technical principles than words. They are more into getting things done and getting results than communicating about how to get these things done.

They might use a lot of jargon. All those numbers, technical terms etc. Do not force your SME to avoid jargon. It is your job as a technical communicator to ask the right questions about the meaning of terms and to decide what information to use.

Make sure that they feel comfortable and appreciated for their knowledge and valuable information. Make sure that the answers to your questions cannot be found in existing material, to prevent losing your credibility in the eyes of a sharp engineer. The best way of interviewing an SME is in person. Alternatively, you can do it with a phone call. Sometimes you will be asked to put your questions into an email or spread sheet.

My experience is that this will delay a project: Answers to questions will lead to new questions. It is your task to keep on asking questions until you understand every bit. Make sure to record your interview. I always use my mobile phone to make videos of all my interviews and when we discuss the full functioning of a product. This will prevent you from asking questions during a second interview or writing down nonsense in the eyes of your SME.

For example: during an interview, SMEs will automatically mention the right names for product elements. You might not remember all of this, but when looking back at your material, you can get out all of this information.

This prevents a lot of frustration. Also, ask SMEs to review your work. Their knowledge and feedback is of vital importance for writing clear information for use. This is the starting point for both interviewing the SMEs and the mapping, structuring and organising your information see next sections. The user s you are writing for might encounter problems during the life cycle of the product.

They want to solve these problems. And that's where they need you for. So when talking to SMEs , gathering information, etc. Typical problems are similar to the above described questions and have to do with the installation, use, maintenance, repair, cleaning and disposal of the product.

In that case you can break it down into chunks. For example, for a type of machinery, called the Roof Washer, we created an instruction manual. One of the main steps that needs to be taken by the user is making the Roof Washer ready for use. You are already starting to create topics now. Topic-based authoring is essential for writing clear instructions.

You are overwhelming yourself with information: from using the product and analysing all available documentation, to the information you get from the experts. This information consists of a description of the problems your users would like to solve, to solutions on how to solve them, but also all kinds of other information such as electrical schemes, spare part lists etc. One of the most challenging tasks of a technical writer is to gather all the information, analyse it, determine what is relevant, delete information, organise and structure it.

This is fairly impossible without mapping out your information. These topics will be clearly organised and identifiable in your table of contents or menu structure, following the life cycle of your product see next section. But before you will have your final, well crafted yes, this should be your masterpiece table of contents, you would like to structure and organise all information. Example of a mindmap.

One single topic gives the answer to a single question a user has. Users want to solve one problem at a time, not multiple. That confuses them. Each topic will have a place in the user manual. A topic can become a chapter or a sub- paragraph. Or maybe a topic fits better in another guide that needs to be created.

The standard for the preparation of Information for Use , structures information around information types and information products. Another way of visualising the relationship between information types, such as topics and instructions, is by means of the following model:.

The information can be structured around several information products that are selected, presented, and delivered in different media to meet the needs of different target audiences.

A user manual or instruction manual is one type of information product. Other types are installation manuals, maintenance manuals, online help etc. A user manual, when printed, is an entire paper booklet describing how to use a certain product. The user manual, installation manual and quick start guide of a product.

A topic can be conceptual e. If a topic is complex, it may contain several chunks, indicated as instructions in the above information type model. Instructions are basically subtopics. A step is a detailed description within an instruction. Instructions contain several steps. Together they describe the step-by-step process of performing a given task.

Each instruction has a clear goal, which should always be task-oriented and to the point principles of minimalism. Each step is task-oriented and enhanced with illustrations. The user follows these steps by reading through the instructions.

You will find more about how to write instructions in the next chapter. Try not to use more than steps when you want your instructions to be effective. Use steps when you want users to memorise a task. This is the magical number of objects an average human can hold in short-term memory Miller, If necessary, a step can be enhanced with embedded safety warnings, tips with a more detailed description on how to perform the step or error recognition in case a step is done wrongly.

It is of crucial importance to format and present information types such as warnings, steps, error recognition, tips, consistently at all times. Consistent formatting will support users identifying the information they are looking for. For example, clear formatting of a safety warning draws more attention to the safety message as the user visually recognises it as being a safety message.

We have discussed several methods and models that will help you map out, structure and organise information.

There is not one single way that works best, but I think a combination of the above mentioned techniques, with some good theoretical background, is the way to write clear user guides. One last thing I would like to discuss is the similarity that I found between the information development process and the product development process. The process of gathering and structuring information is quite similar to this model that I was taught at university, which is used for innovation processes.

At the left, the model describes the basic design cycle. It starts with a description of the function that a product or service needs to fulfill. After a broad analysis of strengths, opportunities, weaknesses and threats, you are able to draw up your criteria list of requirements.

The right model describes the process of researching, idea generation, concept creation and realisation. Each of these stages are characterised by a process of divergence and convergence. You first gather many alternatives before selecting the best ones.

When I apply this model to the process of creating user instructions, it would look like the following:. I would like to talk a bit more about the importance of your table of contents and thus the way you organise your topics in the instruction manual. The table of contents ToC should be incredibly carefully crafted. It should be a well thought-over piece of art.

The ToC is the spine of your user manual! When your users are facing a problem and they want to consult the user guide to find an answer, they will most likely go to the table of contents to see where they can find that answer.

A clear table of contents helps the user to navigate to the right instructions, without having to frantically search through the entire instruction manual. I prefer to organise topics in the ToC based on my audience's needs and the purpose of the information, following the life cycle of the product. Mostly I start with a default table of contents. When gathering information, as described in the previous sections, I write down the names of my topics on post-its, label them and put them on my wall or I create a mind map online.

Example of a default table of contents. When I think all is completed, I add my product specific topics to the default ToC, organise them and finalise my table of contents. Unless artefacts are placed in a page, they are not visible to anybody but you.

You can use files that you uploaded or journal entries you wrote in as many pages as you wish. You only need one copy of your artefact.

Imagine you collected all your artefacts in a shoe box. Whenever you have a new artefact, you add it to the shoe box. When you are ready to create your portfolio, you take a look at the artefacts in your shoe box and choose those that you want to make available on a portfolio page. You can arrange the artefacts on that page to your liking. The diagram below of example artefacts, pages and groups illustrates how content in Mahara can be shared and reused in different contexts and for different audiences.

If you think of LMSs such as Moodle, Sakai and Blackboard as the formal, structured side of e-learning, then Mahara is the social, reflective side.

An LMS and an ePortfolio complement one another in an online learning environment. Since Moodle 2. Mahara has been designed from the ground up to be an open, pluggable system. Creating new artefacts, authenticating against a custom system and much more can be implemented simply through writing a plugin that uses the appropriate core API. What this means is that it is free and easy for you to customise almost anything about Mahara to suit your needs — and paid support is available through a network of Mahara Partners should you require it.

Imagine how rich and interactive your instruction manuals can become! Not sure how Bit can help you write the perfect instruction manual? Bit has a minimal document editor which allows you to write your instruction manual without the distraction of unnecessary buttons and tabs.

Creating an instruction manual from scratch takes a lot of time and effort. You have to research content, come up with an outline, add awesome visuals, and create an overall interactive experience for your readers. Doing this amount of work alone can be pretty daunting and time-consuming. Thus, Bit allows you to work with your peers to get the instruction manual ready as quickly as you can.

Working in teams also allows you to brainstorm ideas together and get your content and design people together in a single workplace. Bit allows teams to collaborate together, give real-time feedback, suggest changes and get work done quicker.

Most importantly, say goodbye to back and forth emails. In this digital age, you need more than just text to engage your readers. All the other document editors limit your creativity by only allowing you to incorporate text and static images in your document. Since instruction manuals are long-form professional documents, having to read so much text can be dull and ineffective. With Bit, you can create smart instruction manuals by incorporating hundreds of file types and making them dynamic and interactive.

Bit also has an automated table of contents based on the headers you add to your instruction manual. Imagine if you were able to track the time spent by readers on these instruction manuals, how frequently they were viewed, and if they were viewed at all. That way you know whether users have actually read the instruction material given to them. Bit allows you to track your documents and gain amazing insights, helping you create an even better version of your documents.

Bit allows various types of teams in marketing, sales, HR, technology, customer service, designers, etc. Since creating an instruction manual is no easy task- you have to research, write, and design it effectively to get the most out of it- we empower teams to get the work done in half the time and with more conviction.

Have a great time crafting that instruction manual with Bit! With this intuitive, cloud-based solution, anyone can work visually and collaborate in real-time while creating internal notes, team projects, knowledge bases, client-facing content, and more.