Skriftlig Info ➜ Writing ➜ How to write good and effective procedures ➜ You must always include notes, cautions and warnings related to health, environment and safety
You must always include notes, cautions and warnings related to health, environment and safety
How to write good and effective procedures
---
---
Use an efficient and consistent structure in the document
Give your document a title that describes its purpose
Use the introduction to define the context of your document
---
Use an efficient and consistent structure in your task
Give your task a title that describes its purpose
Use the introduction to define the context of your task
---
Provide the prerequisites in a short and effective way
Balance the amount of conceptual information
Write simple and easy-to-understand steps
If relevant, include the results of the task
Explain what the reader needs to do next
Feel free to use examples and tips
You must always include notes, cautions and warnings related to health, environment and safety
Not all procedures are easy to do. If you work with advanced equipment requiring special skills, the necessary tasks may also be associated with danger. You will also need to make the reader aware of important issues.
|
It is not mandatory to convey notes, cautions and warnings to the reader. However, it is smart to include a caution or a warning if your product could in some way put someone at risk or if incorrect use could cause damage to it. If a user is seriously injured because he does something you have not warned him against, it can, in special cases, end up in the legal system. It is often appropriate to present important information as a note. |
How should the information be presented?
You must present notes, cautions, and warnings so they are easy to see. This requirement means adapting your stylesheet to highlight the information using visual properties. Here you can, for example, use a different font or size or highlight the text in another way.
Example 1
Here is a "warning" taken from one of my publications:
Use standardized symbols whenever available. ISO 7010 is a technical standard for graphic hazard symbols on hazard and safety signs, including those indicating emergency exits. It uses the colours and principles set out in ISO 3864 for these symbols.
Where will the information be presented?
You must place notes, cautions and warnings close to whatever you want to warn against. In a procedure, you can thus place it anywhere, depending on the message in it.
|
If you work with topic-based authoring, you cannot assume that the reader will see notes, cautions and warnings early in the publication. In such cases, you must include this information wherever you need it. |
Example 2
In a maintenance manual where you explain how to replace circuit boards, include a note about static electricity in every procedure. Use the same annotation throughout. In DITA (or a similar tool), place the annotation in a topic library, and reuse the object in all relevant topics.
Topic-based authoring
In technical documentation, the term topic-based authoring is used for a methodology where the content of a publication is structured in independent topics. Topics can be used in any order within a given publication and reused in other publications. The text in each topic should not assume that other topics are known to the reader and should not relate to others. Context is achieved by publishing different topics in a given order, preferably linked with hyperlinks.
What is important? What should we warn about?
I cannot immediately tell you what is important or what you must warn against. It all depends on your product and what the reader will do with it. Nevertheless, I can give you some tips, without in any way covering all the necessary dangers. Therefore, use this list as a starting point for your own ideas.
Personal protection
Some products are to be used in the home, others in the industry. My products are used on a boat. Depending on the product's characteristics, it is often necessary to specify that personal protection and clothing are important.
Example 3
I use the following text in my sonar manuals:
Installation personnel must wear suitable work clothes. The work clothes must not contain sufficient static to ignite. Always wear a hard hat and suitable protective footwear while handling heavy objects.
There will be a balancing act here. Consider the importance of including such remarks towards the competence of your target group. It is unnecessary to mark information as important if it is well-known or intuitive for your target group.
High voltages
If your product operates with high voltages, include relevant warnings. The warnings must apply to installation, use and maintenance manuals if necessary. Even if you include warnings in the user manual, it is also a good idea to mark the equipment with posters or signs.
Example 4
I use the following texts in my sonar manuals:
The SX90 system operates on 115 VAC and/or 230 VAC at 50/60 Hz. This voltage is lethal! You must never work alone on high-voltage equipment! The hull unit is powered by a 3-phase high voltage.
You must always turn off all power before installation or maintenance work on the SX90 system. Use the main circuit breaker, and label the breaker with a warning sign that informs others that maintenance or installation work is in progress on the system. For safety reasons, two persons must always be present during troubleshooting with the power turned ON. All SX90 system units must be properly grounded.
Heavy lifting
Some system units I work with are large and heavy. Some of them weigh more than a ton. In my books, it is important to specify that the reader sometimes needs help lifting or maybe a crane for the heaviest objects. It is then important that the right equipment is used, both in terms of capacity and certification.
Example 5
I use the following text in my sonar manuals:
The various parts of the system may be heavy. Make sure that the appropriate tools and certified lifting equipment are available. Always wear a hard hat and suitable protective footwear while handling heavy objects.
Notes, cautions and warnings related to tools often belong under "Prerequisites" in a procedure.
Special work tasks
Do you work with products with special properties or that require special expertise? To install a sonar system, you need to weld. We have experienced problems because shipyard workers have welded in tight spaces without removing delicate electronic equipment first.
Example 6
I use the following text in my sonar manuals:
Make sure that installation or maintenance of other equipment in the sonar room does not affect the SX90 system units. The use of heavy tools in the sonar room must be avoided. This includes welding equipment, saws, hammers or similar hand or electrical equipment. Such tools can cause serious electrical and/or mechanical damage.
Here is another example, simply cut from the book:
Special product features
Many products are of such a nature that they set special requirements for installation, use or maintenance. If, for example, you work with Lithium batteries, there are several considerations to consider. These considerations apply not only in the user documentation but also when such batteries are to be packed and transported.
Example 7
In my products, it is important to ensure that no one starts the sonar when the boat is in a dry dock. I, therefore, use the following text in many places in my sonar manuals:
You must never permit the SX90 system to transmit (ping) when the ship is in a dry dock. The transducer may be damaged if it transmits in the open air.
Notes and warning in DITA publishing
In DITA topics you must use the <note> element. This element can be extended using the "type" attribute. For example, you can set type="caution" or type="warning".
Oasis describes the element as follows:
A <note> element contains information that expands on or calls attention to a particular point. This information is typically differentiated from the main text. Variant types of <note> (tip, caution, danger, restriction, etc.) can be indicated through values selected on the @type attribute.
Oasis: <note>, https://docs.oasis-open.org [REF]
Related texts
DITA publishing: DITA Task topic elements
References
- Oasis: <note>, DITA 1.3, 2015, docs.oasis-open.org, (Link)
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.