Meet Serge, the reckless French bunny that improved child safety in trains and accidentally made a statement about technical communication.

Safety signs are a core element of technical communication as well as a source of growing concern. Our lives are increasingly swamped with machines, devices, chemicals, energy, and speed—all of which provide great benefits, but also involve substantial risks. Consequently, as the technical communicators of tomorrow, we need to grasp these issues and put in place the relevant warnings to protect people from danger. 

For decades, technical communication regarding safety has mainly targeted consumer goods and particularly the industrial sector, where workers face multiple risks under the pressure of productivity requirements. As a result, useful guidelines and regulations on safety notes and warning messages have been developed, implemented, and refined, such as the European Machinery Directive 2006/42/EC or the ANSI Z535 and ISO/IEC 82079-1 standards.

The challenges of communicating safety hazards 

What makes hazard communication so difficult?

As far as hazards are concerned, such guidelines often recommend using standardized pictograms and texts to provide consistency, conciseness, simplicity, and comprehensibility across cultures and contexts. Lately though, a growing emphasis has been placed on adapting such standard messages to different target audiences, contexts, and reading conditions (as in tekom’s “Safety Notes and Warning Messages.”) After all, warning signs do not concern solely consumer products and workplace safety (already subject to a remarkable degree of standardization), but also public spaces and facilities. With equal importance, warnings are not always directed to trained workers or consumers in top form. While young children or elderly people will probably never use a steel press or an industrial oven, they may well step on slippery surfaces or go through heavy automated doors regularly. Consider, for example, the multiple hazards that plague public transportation.

Safety signs in public transportation

So, how do conventional safety signs fare in settings like public transportation? On the one hand, mass transit involves obvious risks such as turnstiles, moving vehicles, power, opening and closing doors, going up and down, in and out. On the other hand, commuters include people of all ages, conditions and impairments, often busy or in a hurry. The result is a minefield for technical communicators: multiple dangers to warn about, different audiences with specific needs, and the requirement to be simple and concise. 

Now, think about children. They are curious, restless, easily distracted, and very often either unable or unwilling to read. Write “Keep away!” and kids will already be too close; add a “Do not lean on the door!” sign and they will probably lean on the sign itself. Finally, children can never, ever, be expected to mind the gap. Luckily, very young humans are not the only funny little animals to board trains. In Paris, France, a rabbit has been getting his hand trapped in the subway’s doors since the late 1970s—all for child safety.

How can we adapt safety signs for children?

Hazard communication through cuteness

Our friend Serge was created in 1977 by Anne Le Lagadec (inspired by the endearing lack of prudence of her own pet bunny) and slightly updated afterward. From its very inception, this cartoonish and anthropomorphic rabbit has placed his hand in the wrong place, thus warning about the dangers of automated doors—and beating many expert technical writers in the process. These eye-catching stickers are placed at a medium height (around children’s line of sight), include a caution message (often in several languages), and are highlighted in visible colors, such as yellow, red or orange. Under the message, a visibly surprised and scared rabbit shows both the risky behavior (placing the hand on the door) and its consequences (getting trapped). 

Hazard communication for children: Adapting the standards

So from a technical writer’s standpoint, what standards would be applicable to such a caution message? In principle, warning signs should stand out and include identifiable but abstract pictograms, coupled with a short text specifying the danger involved, its possible consequences, and the ways to avoid it. Nevertheless, when children are the main target group, signs should be adapted accordingly. 

As suggested by a recent research project by Waterson, Pilcher, Evans, and Moore, warnings intended for children should avoid the high level of abstraction so coveted in other, more standardized contexts. According to this study involving 210 British children, conventional signs using abstract pictograms and short texts can be difficult or even impossible for kids to understand. In this sense, the authors make some recommendations to enhance awareness and comprehensibility of the warnings: 

  • Use colors to improve visibility and convey intrinsic information (red for danger, for example)
  • Feature cartoon-like characters that attract the attention of children (such as animals or superheroes)
  • Endow such characters with recognizable facial expressions
  • Use the visuals to show both the cause and the outcome of the dangerous behavior in point

Therefore, we have a complex task ahead of us: assessing the specific needs of vulnerable groups and reconciling them with the existing restrictions and general guidelines. 

Nonetheless, we should not be discouraged. Serge got it right on the first attempt more than 40 years ago and, funnily enough, straight from the pencil of an advertising designer! Little wonder this sticker has become an inspiration for safety signage and warnings in other public transportation systems, home and abroad.

Remember, mind the rabbit!

The TCLoc master’s is proud to announce that it has joined once again the Adobe Tech Comm University Outreach Program. Thanks to this academic partnership with Adobe, TCLoc students will have access to the Adobe Technical Communication Suite in order to gain firsthand, practical experience with these leading software tools for creating and editing technical documentation.

“With our master’s program in technical communication and localization, we seek to provide courses that give students opportunities for hands-on, practical application of the competencies they acquire during their coursework using the best tools available,” says Dr. Renate de la Paix, program director. She continues, “The Technical Communication Suite is the most popular collection of tools used by the industry for creating and editing technical documentation. In our Technical Publishing class, for example, we use Adobe FrameMaker because it allows users to publish natively across channels, mobile devices, and formats, and to create content with best-in-class XML/DITA support.”

The TCLoc master’s focuses on practical skills. By using the latest versions of leading tools such as FrameMaker, Captivate, and RoboHelp, students will be prepared for employment in the technical communication industry. Thank you, Adobe, for enabling our students to use the Technical Communication Suite free of charge for study purposes!

Before the 2019 November on-campus meeting, the TCLoc Team took a trip to Stuttgart for the annual tcworld conference, joining our past, present, and future TCLoc students at this inspiring event.

The tcworld Conference

The tcworld conference is organized by tekom Europe, the largest technical communication association in Europe with over 9,500 members. It takes place in Stuttgart, Germany, every year. The tcworld conference is the largest international event for technical communication in the world, boasting over 4,500 participants as well as over 250 presentations and workshops (in English and in German). Presentation topics cover everything related to technical communication from visual communication and user experience to augmented reality and artificial intelligence.

Speakers at the tcworld conference are all experts in their field and we were happy to see that some of them are also part of our team of instructors. TCLoc’s new instructor for software documentation, Konrad Brust, gave a short, insightful talk about the localization of video games. Shumin Chen hosted a workshop on Simplified Technical English (STE), the subject she teaches for TCLoc. Jordan Stanchev hosted two workshops, “Building Your First Taxonomy for Classification of Software Documentation” and “Visualize It! Creating Graphics and Images in Software Documentation.” TCLoc’s instructor of terminology management, François Massion, gave a presentation on terminology in the age of artificial intelligence. Also, Kirk St.Amant, TCLoc’s usability and user experience design instructor, presented “The Psychology of the User Experience—Approaches to User Testing and Product Design,” which proved to be a conference favorite.

In addition to the numerous presentations at the conference, the tekom fair is also a key point of interest, hosting around 150 software manufacturers and service providers. It is the only trade fair for technical communication worldwide. The conference also welcomes universities that offer bachelor’s and master’s degrees related to technical communication, setting up booths for them to present their programs. This provides the invaluable opportunity for students and educators alike to stay abreast of the most recent developments, standards, and technology in technical communication and related fields. TCLoc, an online master’s program at the University of Strasbourg, is always in attendance.

TCLoc and tekom: Bridging the Gap

This is why the TCLoc Team looks forward to this event every year: tekom and TCLoc have the common goal of bridging the gap between education and industry. tekom organizes this annual event in order to promote and facilitate the exchanging of ideas, research, and technology, thereby driving the industry towards excellence. Conversation and sharing within the industry is necessary to create and maintain standardized best practices in technical communication and related fields. Likewise, communication between industry and education is essential for the proper training and certification of technical communicators. 

TCLoc’s founder and program director, Renate de la Paix, also recognized the importance of this, motivating her to create TCLoc, which is the only online master’s program that combines a degree in technical communication and localization with the tekom certification (offered in the technical communication module, which is identical to the TCTrainNet course -professional level- offered by tekom). Graduates of the program are therefore well-equipped with practical knowledge of technical communication as well as its related fields and tools. The program (including the TCTrainNet course) is constantly being updated to stay on top of new developments and technologies in this ever-evolving industry. It’s partnerships like TCLoc and tekom that promote high quality standards in education and the workplace.

Have you been to the tcworld conference? What did you think? Let us know in the comments below and join us next year at the tcworld conference in Stuttgart, Germany, November 3-5, 2020.

Would you like to validate and increase your experience as a technical writer? Click here to apply to the TCLoc master’s program!

Product documentation can potentially be confusing, incoherent, and ambiguous in many situations. Recognising language ambiguity usually takes months, if not longer.

Several aggravating factors include: 

  • A constant need to churn out or translate volumes of documentation, manuals, and working standards.
  • Rarely questioning the relevance or validity of legacy documentation.
  • Allowing unclear parts of your technical content to snowball into substantial chunks that will eventually make up parts of your “user-unfriendly” help guides. 

Finally, let us not forget the insidiously familiar workplace jargon that often explains why we tend to ignore simpler alternatives that could help us express our thoughts with greater clarity.

From workplace jargon to user-friendly words

Sometimes, realising the level of complexity of one’s technical content involves an epiphany of sorts once the writer catches a glimpse of technical writing in Simplified Technical English (STE). This is true for one of our clients, who is both an experienced technical author and documentation manager:

“A training course helped me better appreciate the objectives of Simplified Technical English from a technical writer’s perspective. I like the fact that STE promotes the use of less complex sentence structures and does away with unnecessary words like: ‘would’, ‘should’, and ‘might’.”

Do we have a problem? If so, fix it!

For example, if you look up the meaning of the word “fix” in a standard dictionary, the definitions are aplenty, from “fixing a technical difficulty” to “fixing up a meal in the kitchen”. Given the many possible meanings that hold true for the verb “to fix”, one could also distil as many interpretations of the word in a sentence.

According to Simplified Technical English, Issue 7, January 2017, there is a solution for this. Instead of “fix”, synonyms such as “ATTACH*”, “SET”, “REPAIR”, and “INSTALL”  powerfully extend our understanding and knowledge of what “fix” really entails when paired with various contextual clues.

© ASD, 2017. All rights reserved. 

The next five words: are you thinking of these too?

Keeping in mind that these are not the only unproductive words I talk about in my workshops, they are among the most frequently discussed ones. 

© ASD, 2017. All rights reserved. 

The word “should” usually indicates duty or correctness that points to a desirable or expected state. However, it still allows the possibility of non-compliance. “MUST”, on the other hand, makes it clear that the instructions are mandatory and leaves no room for a different reading.

© ASD, 2017. All rights reserved. 

Besides the roughly 900 approved words found in the STE general vocabulary, the STE specification also includes a list of non-approved words. “Would” is one of those words that is easily replaced by a more straightforward and approved STE word like “CAN”.

© ASD, 2017. All rights reserved. 

In the STE general dictionary, the approved word examples in the 2nd column are very useful to technical writers who are transitioning from Standard English to Simplified English. This is because they provide the writer with the correct use of words in a real-life context that would be difficult to think of independently. Here, we see that “CAN” is once again a very helpful alternative to the verb “may”. Using too many words that point to the same or similar meanings can be, at times, overwhelming for your readers, especially when documentation becomes lengthier and more detailed.  

© ASD, 2017. All rights reserved. 

By this time, the effects of STE on everyday words that pose as potential roadblocks to concise writing are clear. Instead of “transfer”, STE encourages the use of “MOVE” or “INSTALL”. This adds granularity to one’s choice of verbs, making technical work instructions more detailed and easier to follow.

© ASD, 2017. All rights reserved. 

The preference in STE for the verb “MAKE SURE” over “confirm” is again another unique characteristic of this standard. This is very likely so because the maintenance committee (made up of a diverse mix of linguists, engineers, and translators) deems “MAKE SURE” a more fitting word with more frequent usage to back their word choice. 

What are some popular words in STE that trained technical writers have adopted to date?

We asked over 30 technical writers and this is by far the most comprehensive response to date:

“My favourite STE verbs are ‘APPLY’, ‘ATTACH’, ‘MAKE SURE’, and ‘SHOW’. The verb ‘APPLY’ has multiple use cases for our documents. The verb ‘ATTACH’ is a great utility verb because common alternatives like ‘mount’ are not approved. The verb ‘MAKE SURE’ is extremely helpful in cautions and warnings, as well as in some procedural steps. Finally, the verb ‘SHOW’ is extremely helpful when I write about background processes and how things work in general.” 

STE as a game-changer in our technical communication landscape

Can you envision a future where STE serves as the primary language reference for content creation and development in your field? 

We would like to hear from you. Leave your ideas in the comments section below!

Learn more about what STE can do for different types of documentation here.

Thank you for reading, we hope you found this article insightful.

Want to learn more or apply to the TCLoc Master’s Program?

Click HERE to visit the homepage.

Thanks from the TCLoc web team.


TechCommNZ President Meredith Evans with Steve Moss, Winner of the 2018 Excellence in Technical Communication Award.

Editor’s Note: This article was written by TechCommNZ President Meredith Evans. Enjoy !

In New Zealand, technical communicators are thriving, but there are still many industries and companies that have no idea of what we do or the value we can bring. It’s the role of organisations like TechCommNZ (the Technical Communicators Association of New Zealand) to help change that.

What is TechCommNZ?

TechCommNZ is a professional association for technical communicators, based in New Zealand.

Established in 2007, TechCommNZ strives to represent those involved in any area related to technical communication, information design, editing, proofreading, quality assurance, or documentation. We recognise that our members have a wide variety of roles and responsibilities, with many branching out into related areas such as user experience, business analysis, instructional design, and training. 

But we’re not just about promoting the industry and those who work in it. We also provide learning and upskilling opportunities and the ever-important networking and socialising.

What do we do?

TechCommNZ is a New Zealand-wide organisation, but a large proportion of our members live in one of the three main centres: Auckland, Wellington, Christchurch, and Hamilton. Each of these centres maintains an informal ‘branch’ with activities such as speakers, dinners, and catch-ups. These are usually held outside of working hours, with Christchurch (in the South Island of New Zealand) currently being the most active branch. We also welcome members from outside New Zealand too.

Professional development

A core function of TechCommNZ is to provide professional development for members. We normally facilitate at least two workshops and four webinars each year. Prices to attend are kept as low as possible for members, but non-members are welcome to attend too (at a higher cost!). We’re always on the lookout for interesting topics and presenters, so if you have an idea for a webinar, or even a workshop, get in touch with me by email thepresident@techcomm.nz. Webinars are normally held at a time that suits New Zealand and Australian members (morning Australian Eastern Standard Time) but if you miss the live webinar you can watch it later at a time that suits. 

Conference

Over the past few years, TechCommNZ has held a biennial conference, which moves around the three main centres. However, in 2019 we’re very excited to be taking our conference to the  Tauranga region, located in the gorgeous Bay of Plenty. We normally have between 60 and 90 delegates at our conferences. In 2018, we took part in a huge information technology conference called ITx. TechCommNZ was proud to host a one-day stream at this conference and present Steve Moss, one of our members, with an Excellence in Technical Communication award at the Gala dinner. 

You can read about our 2019 conference here

How we work

Keeping TechCommNZ thriving takes a bit of work. Our Board consists of nine people from New Zealand, and we meet mostly by Zoom (remote meeting). We try to meet in person at least twice a year. We are mostly a volunteer-run organisation. 

I hope you enjoyed reading about our organisation TechCommNZ. If you have questions or just want to chat about technical communication in New Zealand, I’d love to hear from you. You can contact me at thepresident@techcomm.nz or read more about TechCommNZ on our website.

Thank you for reading, we hope you found this article insightful.

Want to learn more or apply to the TCLoc Master’s Program?

Click HERE to visit the homepage.

Thanks from the TCLoc web team.




When it comes to writing technical information, it becomes essential to have good technical writing skills. Indeed this knowledge has to get its point through in a clear and precise way. However some technical information gets more understandable than other. And some content gets more appealing than other. That is because some people have understood that technical writing demands essential skills.

Technical information may be heavy for the reader. Therefore technical writing skills need to be developed to be useful. Here are five essential elements to improve your writing skills and so your technical writing skills.

1. You Are Writing for Human Beings

Never forget this point. Even if robots may have a great influence on the future of your content, people remain the main target audience. Always orientate your technical writing towards people.

Readers Are Different from You

You have to think about who you are talking to. Are you addressing to experts or people who don’t have a lot of knowledge on the topic? Depending on this, you will have to adapt your writing, otherwise your readers may not understand. For example, it may be better to use simplified technical English in your documents.

Adapt Your Content to Different People

Imagine your readers: they will have more or less different profiles. Some will master the topic more than others. To make sure everyone can access your technical information, try to go through your product guessing whether every profile would understand everything easily or not. This is something that can definitely make a difference when creating customer-friendly technical information.

2. Get New Perspective on Your Technical Writing

The more opinions you get, the more improvements you will achieve. Indeed, it is difficult to take a step back on your own technical writing skills because you created it yourself.

Go Back and Forth to Your Production

Avoid writing your technical content at once if you can. Technical information needs to be really clear and precise. And it is easy to lose yourself in the process of writing and think that everything is clear. But the contrary is likely to happen, at least in one part of your content.

What is advised is to take a step back and also leave the content for some time before getting back to it. This way, you will perceive it under a new light and make it better.

Get External Opinions to Improve Your Writing Skills

New points of view can come from the outside. Other people will perceive the output of your technical writing skills another way. Getting these new visions will contribute to improve your writing skills.

3. Make Your Message Clear and Precise

How to improve your writing skills? Your main goal has to make the information consistent and straight to the point.

Avoid Obscure Terms

Sometimes, you will think that one word expresses an idea in a great way. The problem is that people may not understand this word, or the notion behind it. Therefore, even though you are working on a technical topic, you should try to use clear words as much as possible.

Cut Out Superfluous Words

Technical information is not the easiest thing to understand. How can it make it easier when there are many details? When tackling technical writing, you have to go straight to the point. Otherwise, the readers may lose the train of thought and get lost.

Use Time-Independant Information

Your technical content is likely to get around for some time. Thus you have to be careful if you ever use time information. Because depending on when it will be consulted, this kind of information could make no sense. So make sure you use time-independent information.

4. Optimise the Format of the Text

You are sure that technical writing has no secret for you, because you think first of the people you give a message to and also about creating clear and precise technical information. But do you pay enough attention to the looks of your content?

Space the Text and Play with the Font

Text is composed of main words and of grammatical words. You should put stress on the important words to make them striking.

Here are two recommendations to do so:

  1. no blocks : avoid paragraphs of more than two or three sentences. No information will be lost in a sea of words.
  2. italics and bold type : emphasizing the main words of your information is essential to technical writing.

Enhance Crucial Information

There are more ways to enhance important elements in technical writing, so that information is understood perfectly. Here are three must-do:

  1. bullet lists : they are very practical to explain the steps of a process for example.
  2. headings : it is important to find essential information quickly. Headings are more visible than the rest, so make the mos of them!
  3. tables : they definitely help to organise information, depending on the data you have.

5. Create a Visual Article

Linked to the previous point, visuals and multimedia can really help to get your information through. This type of content represent a great backing for your technical writing skills. Visuals are something to remember if you are thinking of gamification marketing.

Get Visual with Photos and Videos

Let’s say it : technical information can be boring and be tedious for the reader to go through. If you want to make your technical writing efficient, think of visuals as a backup. Use images, photos and videos to make your content more alive and less abstract.

Including Graphics is Part of Technical Communication

In addition to photos and videos, you can illustrate information with concrete data. It will help the readers to visualise the information you give and make it clearer.

Bonus: Get a Technical Writing Certification to Improve Your Writing Skills

One great way to improve your writing skills is also to study! You can try to get the tekom certificate, which is highly reputed in the technical communication field. Just know that you can get this certificate and a diploma if you enroll into the TCLoc master’s degree, which will teach you a lot about technical writing. Follow us on our Facebook page or on our LinkedIn profile to get more posts about technical communication and more!

Thank you for reading, we hope you found this article insightful.

Want to learn more or apply to the TCloc Master’s Program? 

Click HERE to visit the homepage.

Thanks from the Tcloc web team

Source

Tracy Osborn, Five tips for improving your technical writing and documentation, August 26, 2016

Nicole Legault, 5 Tips to Improve Your Technical Writing Skills Tom DuPuis, 9 Technical Writing Tips Every Writer Needs to Know, Septembre 27, 2017

Stephen Hawking once said, “Intelligence is the ability to adapt to change.” Constant change, quick decisions, and regular exchange about current tasks are key elements in agile project management. In the 2017 Pulse of the Profession report from the Project Management Institute (PMI), they concluded that “(…) 71 percent of organizations report using agile approaches for their projects sometimes, often, or always”.

In this increasingly agile-working world, the Scaled Agile Framework (abbreviated as SAFe) helps large enterprises establish agile processes on a company-wide scale. First introduced in 2007, SAFe offers comprehensive guidelines, workflow patterns, and consistent terminology. The framework is designed to encourage collaboration and alignment across a large number of scrum teams.

This is the complete SAFe agile portfolio as of SAFe 4.5:

SAFe 4.5 agile portfolio

The SAFe framework considers at least three levels in an organization: the Team level, the Program level, and the Portfolio Level. To find out more about SAFe, how it is implemented and how its components work together, visit the SAFe website.

In recent years, many companies have started implementing SAFe, including Cisco, Philips, the NHS, Intel, and Sony (Scaled Agile Case Studies, 2018). However, any technical writer looking at the portfolio will quickly notice that the portfolio does not mention technical documentation or technical writers – as technical writers, how can we integrate ourselves in this new process?

In one of my SAFe trainings, I asked our trainer exactly this question.

He said that, most probably, SAFe would consider technical writers a Shared Service. According to SAFe, “Shared Services represent the specialty roles, people, and services that are necessary for the success of an Agile Release Train (ART) or Solution Train but that cannot be dedicated full-time.” Shared Services are not part of the scrum teams (called Agile Teams in SAFe), but can support multiple Agile Teams with their skills, as well as other teams on the Program or Portfolio level.

Our technical writing team discussed this solution but concluded that it this approach did not fit our profile one hundred percent. Typical shared functions are only required for one to five features. An example would be the assistance from the User Experience team, which is only required for front-end features.

In contrast, you need technical documentation for almost every feature. The profession includes more than just the writing process, for example the creation of illustrations or multimedia content.
Additionally, although it is a legally required part of the product, engineers might not always understand which features need end-user documentation and which do not. Therefore, it is important for technical writers to be involved from the very start.

Our team tried two different approaches:

  1. Acting as an Agile Team
  2. Acting as a Shared Service

Acting as an Agile Team

The first approach, acting as a separate scrum team that only consisted of technical writers, helped us immensely in being an active part in the PI Plannings. Since we were a separate Agile Team, we had to present our PI objectives and our goals in the PI Planning. This led to an automatic involvement in the decision-making process, and our Scrum Master was part of the Scrum of Scrum meetings. The presentations during the PI Planning increased our visibility to the management and other Agile Teams.

As an additional factor, the predefined SAFe processes helped to align our own team better. During the PI Planning, we would get a better idea of the upcoming features and could plan for their documentation as required. We also allocated time to internal tasks that were documentation-specific, for example clean-ups. It gave us a forum to discuss improvement ideas for our documentation.

However, we still faced some issues: we now had a lot of planning overhead (for example tracking every task down to the hour every day), we kept running into reporting issues, and it was not the proposed SAFe solution.

Acting as a Shared Service

The second approach, acting as a Shared Service, had its benefits as well: we had less planning overhead since we did not have to plan our activities as meticulously. Instead of planning our own user stories during the PI Planning, we had more time to attend the other teams’ planning sessions.

Although this was the proposed SAFe solution, this approach made our presence during the PI Plannings less “official”. We still communicated with the scrum teams to see which features required documentation, but the Agile Teams themselves had less insight into our planned tasks and often had to ask if we had planned in “their” features.

Integrating Technical Writers into the Scaled Agile Framework

Ultimately, we found there is no one-fits-all solution. My recommendation would be to try out different approaches and see which one works best for your team. Consider these two factors beforehand:

  • Your goal: Ask yourself what the issue is with the way things are run now. What is the change you want to see? Our issue was that we did not always have up-to-date information about the features R&D was working on, so we had to make sure we received the necessary input. This worked out best when we were acting as an Agile Team. Your team might have other pressing issues, for example late updates to “done” features, missing updates from the scrum masters, or a general uncertainty about the new processes.
  • Your team size: We noticed that for teams with more than two writers, it made sense to act as an Agile Team and have our goals aligned. But after our team became smaller and consisted of only two writers, we had a higher workload and less time for the planning, so acting as a Shared Service team worked best.

Depending on the company, every technical documentation team works differently and scrum teams apply SAFe in different depths. Make sure to inform yourselves well about the SAFe processes and the Scaled Agile Framework to understand where your team can fit into the portfolio.

… and what about you?

Let us know about your experiences as a technical writer when working in agile or SAFe projects – how does your team work together? Have you tried different approaches to get more involved?

Leave us a message – underneath this blog post, on Facebook, LinkedIn or Twitter!

These days, technical communicators are generally aware that translators almost always use computer aided translation (CAT) tools to work more quickly and produce a translation with the highest degree of consistency possible – given the source text and reference material provided.

This already provides some benefit to translation purchasers in terms of quality. But is there another way in which technical communicators take advantage of the benefits of CAT tools, not only to cut translation costs but improve translation quality during the development and writing stages of technical documents?

If technical communicators have translation in mind from the very start, there are several easy tips and tricks that can be used to reduce costs and improve quality in the long term.

How do CAT tools work?

Computer aided translation tools work by segmenting an original text to be translated into modules. CAT tools use elements such as punctuation marks, cross references, tags and index markers to identify where a module begins and ends. This means that technical communicators need to keep these elements in mind the same way that CAT tools interpret them when planning a document.

The advantage of segmentation by CAT tools is that every translated segment is saved in a database or Translation Memory System and can be reused if an identical or similar segment reappears in the same text or document featuring similar technical language. If a company orders several documents to be translated (and if the documents share a degree of similarity), ensuring an identical format for every document would significantly reduce the cost of each translation. This is because CAT tools automatically complete a portion of the translation based on the segments stored in their Translation Memory System.

Optimizing Form, Content, and Style

When it comes to technical documentation getting the most out of CAT tools, it is imperative that texts are written clearly and concisely formated.

The rules laid out in the international standard for technical writing – EN 82079 – support technical communicators in the development of clear and concise information products. This, in turn, helps translators to produce unambiguous and high-quality translations, without having to spend time explaining every step with the translation purchaser. Ultimately, this means that end users also receive an information product which is easy to read and understand that does not contain confusing, inconsistent or contradictory information.

So, what are these rules?

  • Wherever information (such as warnings or safety instructions) are used in a document, translators should check whether there are previously researched and approved text modules which can be used. There is a good chance that this kind of module has been previously translated. Reusing such modules will keep documents consistent and save on translation costs.   (Tools such as Acrolinx and Congree also come in handy).
  • Always end complete sentences with a period, even if they are short sentences. This will ensure that the translator interprets the type of information in the segment correctly (e.g. a heading vs. an instruction).
  • Avoid synonyms: Every time a new technical term appears in a text, the translator will assume that a new concept is being introduced and will attempt to use a new vocabulary in the translation to describe the concept. Ultimately, the end user might assume that different concepts are being referred to. Using consistent terminology will speed up the translation process and improve translation quality.
  • Avoid run-on sentences, redundancies and ambiguous formulations.
  • Write a new sentence for each instruction. This also increases the probability that those instructions can be reused in multiple sections of a document.
  • Consistently use the same style for the same type of information. For example, use the imperative for instructions and the present tense in descriptions.
  • Never use apparent specifications such as “some”, “several”, “generally” etc. Keep sentences simple and precise.
  • Always provide the text for translation in an editable format. This will significantly reduce formatting costs.

By keeping these rules in mind when developing content, you are already taking a step in the right direction. However, by following and sticking the rules above, developing a detailed information database using will become childs play.

Good luck! Hopefully, it won’t be long until the savings become noticable!

Why care about content quality ?

By and large, content is seen as some type of art project where creativity and writers’ preferences often guide its creation. I expect this to be less and less the case in the future.

As Scott Abel (publisher of the Content Wrangler), states in the interview Understanding the need for content quality management, there are surprisingly few companies that take content quality seriously when it comes to technical communication. Often, technical writers are expected to “wing it” and take responsibility for the quality of their writing as much as humanly possible. This stands in sharp contrast with the translation industry, which has been using sophisticated quality assurance tools for decades, which include:

  • glossaries and terminology banks
  • style guides
  • spell checkers
  • readability scores

However, he states that he expects that the situation will change in the near future, especially given that intelligent content now stands out as a powerful asset for the Industry 4.0. Intelligent content, as explained in this article by the Content Marketing Institute, is content that is “ structurally rich and semantically categorized and therefore automatically discoverable, reusable, reconfigurable, and adaptable.

Improving and managing content quality for technical communication provides substantial benefits:

  • Good source text results in good translation quality, and intelligent content reduces translation costs by increasing text reuse.
  • Consistent terminology is an essential factor for a positive user experience.
  • Systematic content quality checks relieve technical writers from worrying about small mistakes.
  • Well-structured modular content can be output to multiple channels, with little to no human intervention, resulting in time and cost gains.
  • Semantically tagged content is SEO-friendly, resulting in better exposure for the company website, and boosting profits in the long term.

DITA and style guides

DITA (Darwinian Information Typing Architecture) is an open-source xml standard designed by OASIS for writing technical documentation. It is especially suited for intelligent content, since it is based on a modular architecture, where each piece of information (or “topic”) can be reused across multiple documents (or “maps”).

The content is separated from the presentation, which is handled automatically during publication, so that the author doesn’t have to worry about layout guidelines. On the other hand, writing in xml requires a specific set of editing rules – to select the right tag or to impose a certain set of attributes for example. Multiple DITA style guide projects have emerged across the web, the most authoritative being The DITA Style Guide Best Practices for Authors by Tony Self.

Enter the Dynamic Information Model

The Dynamic Information Model (DIM) (1) is an open-source project published on Github created by George Bina (Syncro Soft SRL) with the contribution of ComTech Services. It provides a toolkit and templates to create an integrated style guide in DITA, in which every rule can both be described and implemented within the authoring tool. The toolkit is designed to:

  • Publish an html version of the style guide.
  • Trigger warnings or suggestions when one rule is not respected, optionally with automatic corrective actions.
  • Point back to the rule so that the author can understand the error.

Behind the scenes, the implementation is handled by a library of Schematron rules and Schematron Quick Fix (SQF) actions, as well as XSLT templates to compile the rule set. The project is designed for a full integration into oXygen XML, but it can also be adapted for other tools that provide Schematron and SQF support.

The goal of this project is to be accessible for all technical writers without requiring any knowledge of Schematron, SQF, or XSLT. Each rule is described in a separate topic using DITA markup, in the form of a definition list (dl) placed within a section and marked with a specific audience attribute. The embedded rules use patterns from generic rules defined in a Schematron library. To enforce a rule, the user simply needs to refer to the rule name and specify the parameters.

Some of the predefined rules are:

  • restrictWords: Check the number of words to be within certain limits.
  • avoidWordInElement: Issue a warning if a word or a phrase appears inside a specified element.
  • avoidEndFragment: Issue a warning if a an element end with a specified fragment or character.
  • avoidAttributeInElement: Issue a warning if an attribute appears inside a specified element.

What does it look like ?

Let’s have a look at one of the sample rules provided in the project:

<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE concept PUBLIC “-//OASIS//DTD DITA Concept//EN”
“concept.dtd”>
<concept id=”AuthoringGuidelines”>
<title>Beginning a Topic</title>
<conbody>
<p>With the exception of glossary topics, you must include a title   and prolog section before you begin the body of the topic. In addition, you can optionally include a short description of the topic. The following sections provide guidelines for these common elements.</p>
<note>
<p>When creating a new topic, always start with the <keyword keyref=”companyname”/> template for the corresponding information type, if one is available. If you copy another topic, you could
inadvertently duplicate element IDs and you risk overlooking elements that you might need for the new topic that were removed from the topic you copied.</p>
</note>
<section audience=”rules”>
<title>Business Rules</title>
<p>We will recommend adding a prolog to different topic types, except for the glossary
topics.</p>
<dl>
<dlhead>
<dthd>Rule</dthd>
<ddhd>recommendElementInParent</ddhd>
</dlhead>
<dlentry>
<dt>parent</dt>
<dd>task</dd>
</dlentry>
<dlentry>
<dt>element</dt>
<dd>prolog</dd>
</dlentry>
<dlentry>
<dt>message</dt>
<dd>A prolog is required for each task. Add this just before the task body.</dd>
</dlentry>
</dl>
<dl>
<dlhead>
<dthd>Rule</dthd>
<ddhd>recommendElementInParent</ddhd>
</dlhead>
<dlentry>
<dt>parent</dt>
<dd>concept</dd>
</dlentry>
<dlentry>
<dt>element</dt>
<dd>prolog</dd>
</dlentry>
<dlentry>
<dt>message</dt>
<dd>A prolog is required for each concept. Add this just before the concept body.</dd>
</dlentry>
</dl>
<dl>
<dlhead>
<dthd>Rule</dthd>
<ddhd>recommendElementInParent</ddhd>
</dlhead>
<dlentry>
<dt>parent</dt>
<dd>reference</dd>
</dlentry>
<dlentry>
<dt>element</dt>
<dd>prolog</dd>
</dlentry>
<dlentry>
<dt>message</dt>
<dd>A prolog is required for each reference. Add this just before the reference body.</dd>
</dlentry>
</dl>
<dl>
<dlhead>
<dthd>Rule</dthd>
<ddhd>recommendElementInParent</ddhd>
</dlhead>
<dlentry>
<dt>parent</dt>
<dd>troubleshooting</dd>
</dlentry>
<dlentry>
<dt>element</dt>
<dd>prolog</dd>
</dlentry>
<dlentry>
<dt>message</dt>
<dd>A prolog is required for each troubleshooting topic. Add this just before the
troubleshooting body.</dd>
</dlentry>
</dl>
</section>
</conbody>
</concept>

This editing rule stipulates that each topic, except for glossaries, must start with a title and a prolog. Since titles are already mandatory in DITA, only the prolog rule must be enforced. The definition list references the predefined pattern “recommendElementInParent” and associates the parameters “parent” with each topic type, “element” with prolog, and “message” with the message that must be displayed in case the rule is not followed.

Making it your own

In order to extend the rule patterns library, users should get to grips with the basics of Schematron. Schematron is a basic xml-language used to search patterns in xml files. When a pattern is found (or not found), a defined action is performed, which can be an automatic correction, a suggestion or a warning.

Find out further information here : Schematron: a handy XML tool that’s not just for villains! 

(1)Apache License 2.0, copyright Syncro Soft SRL – 2015

Knowing the technical information of a product is essential when it comes to using it properly. However, getting to know  and keeping in mind all that information can be an ordeal for anyone. One solution however, which primarily deals with the accessibility of technical information, is making waves: gamification marketing. By means of a reward-based system, the learner feels more involved and is more likely to assimilate information, which will inturn make your technical information more efficient.

Gamification Marketing: a reward-based system?

Gamification marketing is a technique that consists in applying fun and engaging elements to something that  may not be quite as amusing as a game. The aim is to increase  overall user engagement.

A common technique related to gamification is the attribution of rewards. Users can get points as they would for a loyalty card, or maybe more practical rewards like a better parking spot. This way, things feel far less like a boring and time consuming chore like they probably would have before.

Getting your teeth into the technical information of a product can be quite time-consuming  and challenging for some. It’s in your best interest as a technical writer to avoid turning the experience into an ordeal. Instead, try making it engaging and fun!

Gamification Marketing takes a creative mind

Applying gamification marketing to technical communication will probably mean that you’ll have to call on your creative flair. You want to make the user   carry on reading. Think of your technical information as educational material: the aim is to facilitate user learning and even to help them look for more precise information. In fact, integrating games into education is a strategy that is being deployed more and more   in schools.

But can you make technical information about  a product more entertaining? Several elements have been proven to stimulate learner’s brains more than others. :

  • Visual : For users who have a visual memory. Images, pictograms and flash cards naturally help them to better process information.
  • case studies : practice makes perfect ! By solving problems, users will understand the importance of the technical information and how useful it is
  • quizzes : aiming to get good results, this will engage even more the learners. They can even lead to create some sort of competition, which is stimulating as well.

Gamification Marketing Leads to More Efficient Technical Communication

Because of their interactive nature,  such stimulating elements will naturally make your technical information more efficient. Users will find it easier to learn  and will be generally more focused. This interactivity will include the reader and inspire them to develop their technical knowledge.

For her Master’s thesis, Anna-Lotte Wienstroer tackled the  topic of gamification marketing and led a study to find out  whether it was more efficient than a traditional paper-based manual to learn technical information. In the end, it was concluded that employees learning through gamification made less mistakes than the ones with the paper copy . One thing that should be pointed out however : gamification was generally more effective for younger generations. Another issue raised wasadapting the  technical information to the target user.

To conclude, gamification marketing is one technique you can use to make your technical information more attractive to users of your product. If you let your creative skills run riot,  your users will feel more engaged, and the technical information will be taken on board more efficiently and for longer periods of time..

References:

Anna-Lotte Wienstroer, “All fun and games”, October 2018

Theresa Pojuner, “Gamification and Technical Writing“, August 2012