As you encounter any issues with styles, you can create your own additional style rules that address the specific needs of your project. If you would like to become a technical writer, you may want to consider registering for our Professional Technical Writing Course. It is an online course where you will learn how to write and revise instructions, technical reports, and software manuals key technical writing documents. Use active voice Active voice emphasizes the user and is easier to read and understand.
Compare the two sentences below. Focus on the reader User manuals should always focus on the reader. Speaking directly to the reader will: Reinforce the message that the information is intended for the reader Pull readers into the document and make it relevant to them Help to avoid passive voice by focusing on the reader Compare the two sentences below.
Write clear instructions The primary objective of user manuals is to help users complete tasks. Use numbered lists for instructions unless the instruction includes a single step. Use parallel construction for each step. When you start each step with an imperative word, you are providing the user with clear cues on the required action for each step. Avoid using a system response as a step. You can incorporate system responses when necessary in the step that initiated the system response or you can mention the system response at the beginning of the following step, e.
An operations manual is a magical solution that will help you streamline your business! It not only improves the scalability of your business but covers different business aspects such as employee training, marketing, knowledge management, SOP, and much more. Operations manuals may differ from company to company and they may also vary in size; while some companies create operations manuals that are multiple pages long, some stick with a few documents. It is an insightful set of documentation related to all the company know-how.
If created correctly, it provides guidance to someone, unfamiliar with the day-to-day plan of action for operating your business. This official document is a way of ensuring that you and your team can efficiently carry out tasks with constant results.
With an operations manual, human errors are minimized and everyone in the organization accurately knows what they need to do to get those results, how do they deliver results, and to whom! In a team, someone or the other always has a question and is looking for a quick answer! Hence, it becomes chaotic to hand-hold others with every issue, this is why you need an operations manual that does it for you.
So, other than just scaling and reducing human errors, there are several other benefits to using an operations manual mentioned below:. With a lack of clear process documentation, your team members or employees are likely to do things in their own way.
When it comes to business procedures, you want everyone to be on the same page with maximum efficiency, which means having a specific structure on how to do the job and be as efficient as possible!
An operations manual helps you document business processes and support your employees on how to get the job done to perfection. You and your team know what it takes to deliver the right product or service. However, all this know-how can be lost if a handful of key employees holding the relevant knowledge leaves the organization. In such cases, the company needs to set up a process of passing all the knowledge and assets of these employees to their co-workers. We can tailor our user research and design courses to address the specific issues facing your development team.
Users don't always know what they want and their opinions can be unreliable — so we help you get behind your users' behaviour. Comment, share or save this article opens a new browser window.
Photo by Fernando Venzano on Unsplash. About the author. If you liked this, try… Help! What The Beatles can teach us about writing support material 37 usability guidelines for help, feedback and error tolerance 23 writing and content quality usability guidelines Red route usability Usability Test Moderation: The Comic See all usability articles and resources.
Download the best of Userfocus. For free. Jun 5: Why you don't need user representatives May Should a design agency test its own design? Our most recent articles Dec 2: Usability task scenarios: The beating heart of a usability test Nov 4: Common traps in user needs research and how to avoid them Oct 7: Transitioning from academic research to UX research Sep 2: The minimalist field researcher: What's in my bag?
Aug 5: The future of UX research is automated, and that's a problem. Our services Let us help you create great customer experiences. User experience research User experience design User experience training. Using these words will make your user manual ambiguous. If you tend to use these words, you most likely still lack information. So ask someone or find unambiguous alternatives. Clear and to-the-point use of words will help the user to complete an action as safely and quickly and as well as possible.
An action-oriented approach should have priority in general. Your user should be provided with an immediate opportunity to act. Using Simplified Technical English can help you to write unambiguously. You can provoke action by giving less conceptual information and focus on giving procedures: users want to get stuff done and not read about it. The best way to learn is to act.
At the same time, often users need to learn first in order to act. Look at this example based on the principles of minimalism , that contains this balance:.
In much conventional user documentation, not much priority is given to supporting actions a user needs to perform at the beginning of the instruction manual.
Many user manuals start with explanations, technical data, safety instructions, process descriptions etc. This, for sure, can be valuable information at some point, but mostly distracts the users from getting to their goal. Try to include only the absolute minimum of must know information in your user manual and consider all the nice to know information as obsolete. The user guide stimulates a user to activate relevant prior knowledge and to depend more on their own thinking when you do not explain everything.
When you master the skill of minimising background information and provide just enough information so that the user can complete a task or understand a concept, your instructions will become much clearer. Many user guides contain instructions that are incomplete or incorrect.
When writing, it might help you to perform all of the steps yourself as you write. This ensures that what you write is the right way to do things and it helps to focus on the must know information.
It will also increase the chance that nothing is forgotten and the overall quality is improved. In those cases, discuss all steps with an SME, think them through thoroughly and have everything written checked. Make sure to provide step-by-step sequences that are placed in the correct order and follow the timing and sequencing of the actual operations. To select German as your default language, select Deutsch when clicking on Language in the File menu. This example shows visual stepping stones: steps are numbered with 1, 2 etc.
Adding these makes it clear to the users that there is a need to follow the steps one by one. Short, simple sentences with just one instruction, or at most a small number of closely related commands, per sentence work best. Write the steps to task completion, meaning that you tell the user exactly what to do in order to complete a single task. Avoid creating dead-ends and make sure that after going through the sequence of steps in a certain topic, the user has solved the problem: each topic has a clear beginning and ending, this is in contrast to a book that you read entirely from beginning to end.
Make sure that the information you give is as simple and as brief as possible. Instructions should be written in the present tense and active voice, using strong verbs. The active voice emphasises the user and it is easier to read and understand instructions that are written using the active voice. In this sentence, connect is the active verb and keyboard , USB port and remote unit are all subjects. It is much clearer that the reader is the person who will complete the action in the sentence written in active voice.
By using the active voice , your instructions will be clearer, more concise, and direct. It is ok to incorporate product or system responses when necessary in the step that initiated the response. Every now and then you might want to add cross references to your instructions. For example, you might want to refer to a sequence of steps that have been given somewhere else in the instruction manual.
Or you simply want to refer to an entire section. Example of a cross reference to the entire section Safety Information. In general, cross-references should be kept to a minimum. Letting your users go back and forth through the user manual is not user-friendly and confuses them. Referring to a complete section like in the example above , which is an addition to a certain topic but a topic on its own, generally is ok to do. I have emphasised the importance of consistency several times already, but I will mention it again here: it is crucial to express terms, product elements and units in a consistent manner.
Use consistent terminology in the instruction manual themselves, on the packaging, in other collateral materials and on the product itself marking and labelling. Of course, sentences should be grammatically correct, written for the target audience, and jargon should be minimised.
Avoid abbreviations and acronyms, unless it can be assumed that they are familiar to the audience you write for. Your user already bought the product. All of the above guidelines can be put in a style guide. A style guide provides consistency and stimulates to carefully consider all details: the presence of a style guide will force you to look closely at each single sentence. Once you have established your own style guide that covers for example your writing style, wording, consistent use of terms, ways to address the readers and design of text and page layout we will discuss this later , you will need to apply it to the entire instructions for use.
Regardless this is a U. S standard, I also like to apply it to the instruction manuals we write for other markets. The ANSI standard states that the correct verb form for indicating a requirement is shall.
The word shall is understood to be mandatory. The universally accepted use of must instead of shall is not recognised by the standard. For example: The product shall only be used by persons who have fully read and understood the contents of the User Manual. The correct verb form for indicating a recommendation, as defined by the ANSI, is should.
Or to speak in ANSI terminology: should is understood to be advisory. For example: After each use, the device should be disconnected from the mains. When there is excessive freedom of behaviour, or no guarantee that something will happen, you can use the word may. This word is understood to be permissive. Using might instead is not allowed. For example: Some individuals may experience a mild tingling sensation when first using the device. I have experienced a situation where U.
No matter how well a product or piece of software has been designed, things undoubtedly go wrong when using it. As a technical writer you should pay attention to this. Users of products make many simple mistakes. Correcting these mistakes can be time consuming.
So it is therefore important to add error information to instructions that users might misunderstand. Providing error information AND providing it there where it is needed, is one of the most underestimated aspects of user documentation.
There are several ways how well-designed instruction manuals can prevent users from making mistakes. For example by providing a safe sequence of steps, using short and simple sentences, minimising jargon, using active verbs etc. Research [1] has shown that even experienced technical writers generally do not predict really well what problems arise when their documentation is used.
The best way to find out what errors users will face is by usability testing. See Conduct user research to check what you have written. When you have found the most common errors that occur, a model for adding problem-solving information to your user manual suggests the following stages:. In other words: when designing error-information, make sure you support the user in detecting, diagnosing and correcting mistakes. Error information is most effective when it is given as near as possible to the source where and when the error occurs.
This is often directly after a certain instruction. When providing error information on the spot, the mistake will be detected and hopefully solved, before they can lead to other mistakes. When you provide the error information on the spot, it will save your user time, reduce frustration AND the anxiety of learning about using the product. I discuss this in more detail in this podcast :. First of all, because it has to do with compliance, which is a largely overlooked topic by most tech writers.
Information on compliance, product safety and what exactly to include in your user manual is hard to find. The websites of our legislators can be quite overwhelming. Secondly, I like the contradiction between creating a compliant and user-friendly instruction manual at the same time. Some technical writers like to over-warn. I have seen user guides with nothing but warnings and really not a single instruction. Over-warning is at odds with an action-oriented approach.
What would your user experience be when a 40 page instruction manual has its first actual instruction on page 32, after more than 30 pages of warnings and process descriptions? No matter how well and safely designed a product is, using a product often comes with certain risks. Risks can be identified by conducting a risk analysis. It is generally agreed in international standards that there are three ways to reduce those risks:.
You can adjust the design of your product, equip the product or user with safety measures such as safeguards, personal protective equipment or provide safety instructions. These three risk reducing measures should be considered in this specific order. So a user guide should never be used to warn for risks when the design can still be improved.
For the user manual this means that there can be distinguished four types of safety instructions: supplemental directives, grouped safety messages, section safety messages and embedded safety messages see this post for more information about these. Considering the number of warnings, the use of this electric toothbrush seems just as dangerous as working on a nuclear power plant. I am not saying not to use any warnings at all, but it definitely is possible to reduce the number of warnings drastically in many cases.
When you do decide to provide a warning instead of an instruction, make sure to structure the warning well. Nowadays, the meanings of signal words are similar in several available standards describing risk levels. Signal word used to indicate an imminently hazardous situation which, if not avoided, will result in.
Indicates a hazardous situation that, if not avoided, will result in death or serious injury. Signal word used to indicate a potentially hazardous situation which, if not avoided, could result in. Indicates a hazardous situation that, if not avoided, could result in minor or moderate injury.
Depending on the product you are writing for, chances are there are legal requirements on the content, presentation and format of your user guides. These can come from federal laws in the US, directives or regulations in the EU or similar legislation in other countries or states. Standards can be used, if not made mandatory, in order to comply with the CE requirements. For example, medical devices are the most heavily regulated products. By complying with the legal requirements and applying standards, you create a user guide that is legally compliant.
This will help you to avoid any legal pitfalls, will let your product pass tests and customs, decrease your liability, provide competitive advantage and make sure your users can use the product more safely. Generally speaking, the following process should be followed to create compliant user manuals:.
I have written about this process in more detail for both the American market and the European market. Also, these templates might help you create CE-compliant user manual template for machinery , user manuals for electronic devices and toys, or the instructions for use for medical devices.
Also for the US, we offer templates for machinery and medical devices. How to use the Operator Manual Template for to create a machinery manual:. An essential part of a clear user manual is the way your user can navigate to the information they are looking for. Much of this has been discussed already in the previous chapter. But there is more than adding a table of contents, page numbering, clear headings and a logical structure.
Instead of ordering your topics according to the life cycle of a product from unpacking to disposal , you might want to divide your section ordered by chronology of use, expertise level beginner or expert , functional category or frequency of use. You can code your hierarchy with tabs or colours or emphasise the importance of certain information types with contrast, colour, shading and embolding, which is actually part of how you present your instruction manual see Chapter 4.
Another way of guiding your user to the right information is by including an index or glossary. An index is an alphabetical list of names, key words, product elements, life cycle stages etc. A glossary is an alphabetical list of words relating to the specific subject you are writing about, with explanations. So it is actually a brief dictionary.
Example of a glossary. Once you have used all these tips and examples to write the content of your manual, it is time for reviewing your work. You have now created the draft version of your instruction manual. Internally, we name this version the textual content design we could put this one in the glossary, lol. Ask all persons with in-depth technical product knowledge that contributed to delivering information, to review the work so far.
I prefer to work with a technical authoring tool for the review process or simply via Google Doc. Visuals include all kinds of graphical representations, such as line drawings, photos, screenshots, video, symbols, tables, charts, graphics and infographics. You can use line illustrations to support, replace or augment text and to present a chronological sequence of a process or steps to be followed.
Make sure that the sequence of illustrations that you place in your user guide is logical and comprehensible. When you place illustrations as close as possible to the text to which they relate, it is clear to which textual instruction they belong. Ensure that related text and illustrations are viewable at the same time and that they support each other in order to enhance comprehensibility.
Compared to photos, you have much more freedom with illustrations to focus on important details. You can easily leave out less relevant information or enlarge certain parts.
Keep in mind that creating comprehensible illustrations requires skills. Although there are many tools available that can support you, having them created by a competent graphic artist or technical illustrator might be a wise decision.
When creating illustrations, keep printing quality or screen resolution in mind. Illustrations used on screens require a resolution of 72 dpi and, for print, resolutions of minimum dpi are preferable.
Add numbered captions to your illustrations so it is clear to the user what the illustration is about and so the illustration is easy to identify when referred to in the text. Illustrations can also be used to identify product parts and main functions, represent a schematic version of your product or for example the electric scheme. Sometimes photos are used instead of illustrations. However, I really prefer the use of line illustrations as these are often much clearer.
When creating illustrations, you can leave out irrelevant information or easily emphasise important information. With photos this will be more complicated. Screenshots can be used to visually represent the user interface of a control panel, software on a desktop computer or an app.
Screenshots can give an overview of functionalities or be used to show what needs to be done or to present the result of a certain action. You can use tables to organise numeric or verbal data. For example, technical data are more legible when presented in a table.
In many cases, a table can fully replace text. Make sure to set out tables clearly, informatively, and in a consistent design.
0コメント