Software writing technical manaul

Your comment. This site uses Akismet to reduce spam. Learn how your comment data is processed. Delivered by FeedBurner. Subscribe in a reader. Please visit the contact page for all inquiries. Share this:. Leave a comment Cancel reply.

The Edit Blog Welcome to the Edit blog! We publish mostly editing, writing and language related articles written primarily by our incredible staff. Our articles range from highly technical, expert level PhD advice, to silly writing-related humor. We hope you enjoy, and if you have any suggestions or you would like to write an article for us, please reach out to us on the contact page or leave us a comment on a post.

Enter your email address: Delivered by FeedBurner. Subscribe to Edit Editing Service by Email. Jan 13th, Plot-Driven Stories Vs. Subscribe Subscribe in a reader. When you pay no or too little attention to the description of the reasonably foreseeable misuse, it may affect your liability as well. For example, when it can be reasonably foreseen that a certain cooling system used in hospitals, may be used as a system to cool organs, this should be described in the instructions.

Unforeseeable misuse should not be included in the instructions as this generally speaking does not affect your liability. As discussed previously, an instruction manual consists of various kinds of information that serve a specific purpose, called information types. When you format information types consistently, your reader will consciously or subconsciously recognise them and link it to the function of the information type. The layout of the information type makes it easy to distinguish the various elements of information.

A different layout will facilitate differentiation between various information types. See this example where the heading, instruction title, instructions, product elements and illustrations are all information types that have been formatted consistently throughout the user manual. Using a style guide helps you to write and format documentation in a clearer way, and to keep a consistent tone of voice and style. Another thing to be aware of when creating clear instruction manuals, is to avoid vague words.

Examples of such words are thing, part and stuff. 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. Position tables next to the relevant text. As an exception, reference tables such as a spare part list can be placed in annexes.

The use of video could be your choice when you clearly want to demonstrate something, show movement, a state or force. Also, as video is increasingly popular, you might want to use it when reaching as many people as possible is your goal.

Video can be realistic filmed with a camera , a 3D animation or an illustrated animation, as long as you keep in mind that videos should be short and relevant. When using video, synchronised spoken or written text, or both, can be used to accompany the sequences.

Another increasingly important form of animation, is interactive animation. Interactive animation can be best described as a sequence of visual and auditory elements. It can best be used to explain complex processes, such as a sequence of installation instructions.

When done correctly according to minimalism principles , video and interactive animation often is more effective than any other form of instructions. According to research, viewers remember information for a longer period making it more effective and viewers learn quicker making it more efficient.

Keep in mind that, as video might require a stable internet connection, it is less suitable in areas with bad reception. Have a look at this incredibly funny video of Virgin America in which they present their safety instructions. You can use infographics, graphics, charts and diagrams to show patterns, organise and visually present data, show relationships, create overviews etc. Symbols, icons and safety signs are often used in instruction manuals.

They are characterised by having a predefined and clearly identifiable meaning and are used to transmit information. If a graphical concept is represented by a graphical symbol registered in a standard, it is highly recommended to use this symbol. Examples of clear icons according to ISO Icons can be used to represent objects or functions. Make sure you use them uniquely and consistently for just one purpose. Never use different icons for the same object or function. For more directions on when to use text or visuals, see this post.

Luckily, more and more companies see the importance of both an attractive design and the use of several media to bring the information to the reader. There are many ways to communicate the use of a product with its user.

You can determine the media of the information based on the needs of the target audiences. Make sure that the media provide easy access to the information throughout the intended lifetime of the product. Therefore, always keep in mind the lifetime of the product and even consider mentioning it in the instruction manual.

Some examples of possible media for user instructions are text, visuals photographs, safety signs, graphical symbols and illustrations , video including auxiliary means such as audio and subtitles , animations, speech, braille, augmented reality, virtual reality, leaflets or stapled booklets with text, illustrations and printed information on the packaging or on the product itself.

Although regulations slowly become less strict, always inform yourself about any legal requirements on the publication form in the country where you are selling your product. See this article about online publication as well. Available technical authoring tools can help you to create both online and print user instructions, using the same single sourced content. Single sourcing with MadCap Flare. Regardless of the chosen medium, it is also important to format the information for both the media and the target audience.

Use a clean, readable sans-serif font. Ensure that the font size fits the needs of the audience. Avoid using multiple font styles. Use bold, italic or courier typeface for terminology, reference information or input. Information that is printed onto. When information is only given on the packaging or in materials accompanying the product, make sure it is in a durable form. It should survive frequent use during the lifetime of the product and in an environment where the product is intended to be used.

Part of how you present your user guides has to do with the language. Lastly, the most important thing to consider in making the Manual is the content. Lay- outing and design are also important, but without good, informational and understandable content, the Manual will lose its purpose. Manuals are a form of communication. Thus, it needs to be understood by readers spanning from varied demographics and background.

I am really happy to read this weblog posts which carries tons of helpful facts, thanks for providing such statistics. Your email address will not be published. Save my name, email, and website in this browser for the next time I comment. Skip to content Like Us On Facebook.

Contents 1 Effective tools to create and design Manuals 1. Manual Master Makoto.