Product Spotlight: Linda McGovern on Admonitions in a CCMS

What should technical writers consider when creating manuals that use admonitions and safety messages? And how can a component content management system (CCMS) help with organizing and reusing admonitions? We asked Linda McGovern, Solutions Engineer at Paligo, to give us her best tips and advice.

Linda has over 25 years of experience in managing technical writing in high-tech, software and hardware industries. After several years working in the United States, she now lives in her home country of Ireland and joined Paligo a year ago, working with sales and customer success. She’s experienced first-hand the difficulties of managing admonitions in multiple languages.

Linda McGovern: I think admonitions are very valuable pieces of information. An admonition is basically a text that stands out from the rest of the text in a manual or other technical documentation. Admonitions can be notes, tips, warnings, cautions, or any kind of text related to safety information. Admonitions are very common in the hardware world, but they can also be used in industries for software, finance, insurance and medicine.

In the case of hardware documentation, admonitions are used in deployment or installation guides, and are usually identified by an icon. It can be a note in a box saying, “Don’t stick your finger here” or “Don’t open the top of the device and remove the fan,” or anything like that. Admonitions both help ensure safety and protect the company from liability.

Linda: Basically, admonitions provide the safety information that regulatory bodies or import agents need when you export products or hardware to other countries. They’re looking for key statements, and if you don’t have those statements in order, or if they’re slightly different across different manuals, then your shipment can get held up at customs.

This happened to me at one of my positions before Paligo. The company I was working at was exporting hardware to South Korea, and I got a call over the Christmas holidays from our export team saying that customs couldn’t find the warnings they were searching for. The translated warnings were there, but just written in a slightly different way than they were expecting.

Back then, admonitions were a thorn in my side; they were extremely important, but if we didn’t have them correctly translated, word for word, nobody could find them. If, back then, I had a better way of organizing them, with one source version of each admonition, my life would have been so much easier.

Linda: Before I came to Paligo, I had never used a CCMS. We were shuffling around hundreds of admonitions on an Excel spreadsheet, with one spreadsheet for the English source language, and a separate spreadsheet for each translated language.

But the spreadsheets weren’t really connected, so we needed a person whose job it was to keep track of them. This was really time-consuming, since you couldn’t change something in English without making sure it was changed in exactly the same way in all the other languages. Without a CCMS, we didn’t have a better way of doing it.

Linda: When you use a CCMS like Paligo, all your admonitions are connected in a database, including the source language and variants, which helps keep them consistent and easy to find. If you translate an admonition into French or German, there’s no guesswork involved in finding translations and keeping them up to date.

At other companies I worked at, we had DITA XML under our belt, but we really didn’t have a simple way of reusing content. With Paligo, you can write an admonition once and then find it again to reuse it many different times. For technical writers, this is a huge time saver and ensures consistency in messaging, and for companies it’s a security blanket, knowing all this key content is clearly organized and reusable.

With Paligo, you can categorize your content using taxonomies, making it easier to find related topics and images. If you’re exporting your products to another country, this makes it easier for you to locate the specific phrases that customs or regulatory agencies are looking for.

Linda: One tip is that writers should try to keep their admonitions as concise as possible. The longer the admonitions are, the less likely it will be that people will understand what they should or shouldn’t be doing.

It’s also important to have native speakers write the admonitions, so they are clear and easy to understand. If you have designated writers for admonitions, you can avoid everyone writing the same warning in a slightly different way. Since Paligo makes it easy to reuse admonitions, this ensures this valuable content is consistent.

With Paligo you can also customize the style of your admonitions. Some companies need to follow certain regulations or requirements when styling admonitions, like using exclamation points or red backgrounds, and Paligo makes it easy to set this up, and use your custom iconography.

Linda: It really depends on the customer, but for many smaller companies, they’re impressed by how easy it is to quickly publish content with Paligo in different formats. Within a short time of first using the system, you can publish content as a PDF or HTML5, or push it to Zendesk or Salesforce. Our multi-channel publishing has been a big aha moment for them. They don’t have to be an expert in DITA, XML or layouts, since Paligo takes care of everything for them.

Linda: I love working in an industry that I’m very passionate about and helping people increase their workflow productivity. At Paligo, I love being able to show customers, whether they have one technical writer or 20, that there is a more efficient way to work. If I had Paligo when I was a tech writer or manager, I would have been so much more productive and happier!