Writing Archives | Rubric

Ian Henderson
May 14, 2019
manual-1280x851.jpg

Technical writing invariably involves a great deal of content reuse. If you’ve ever authored technical documents across multiple products and projects for the same organization, you’ve undoubtedly found yourself repeating elements of text and style many times over.

Streamlining this content reuse can be one of the best ways to improve the efficiency of your authoring and localization processes. And, with the right tools and strategy, it’s easier than you might think.

The Darwin Information Typing Architecture (DITA) is an open standard, XML-based architecture for writing and publishing technical documents, and it was built from the ground up to support content reuse. DITA encourages a modular approach to technical writing where topics – the basic units of information within DITA – are capable of standing alone and being reused in many different documents. The focus is on content rather than layout, with the goal of maximizing reuse to save time and resources.

DITA was originally developed by IBM almost 20 years ago. It has received numerous updates since then, and it is experiencing a renaissance with the release of new tools and Lightweight DITA – a simplified version for those that do not require the full feature set, or prefer to work in HTML5 or Markdown.

Switching from traditional word editors to DITA can seem like a daunting prospect, but if used correctly, DITA is an invaluable tool that drives effective writing and localization. That’s why we’ve put together this article to give you some tips on how to get started.

 

The right tools

The first stage in any DITA implementation is choosing your tooling. If you’re new to the architecture and looking to explore its potential, the DITA Open Toolkit is an excellent starting point for experimentation. It’s a free, open-source publishing engine, and it actually serves as the foundation for much of the DITA software ecosystem – including many of the most popular, proprietary authoring and content management applications.

Oxygen XML Editor 21.0 interface
Oxygen XML Editor 21.0 interface

 

 

 

 

 

 

 

 

 

 

 

 

When you’re ready to implement DITA in earnest, tools such as Oxygen XML Editor are the natural next step. This kind of software provides an easy-to-use visual interface for creating and editing technical documentation, much like a typical word processor. But unlike a word processor, these tools come with built-in DITA support, enabling writers to manage their modular content units and effortlessly reuse them via content references.

Content References can be used to pull a huge variety of previously-created content into a new project. This can range from a single phrase, to a topic, to an entire collection of connected content.

 

Don’t let localization be an afterthought

The benefits of DITA aren’t limited to the initial authoring process – it can also significantly streamline localization. The key here is to make sure that you factor in localization right from the outset.

Content created in DITA can be easily converted to XLIFF for translation. But before you get to that point, there are a number of things you can do to make your content more localization-friendly:

  • Write in International English rather than American or British English. Avoid colloquial expressions, idioms, and overly complex sentences.
  • Determine whether there is anything that should not be translated, such as lists of parameters and part numbers. Most DITA tools will give you the option to flag this content for exclusion, which can make a huge difference to localization costs by reducing the scope of work.
  • In cases where you need to customize your content for different products within a range – or for different outputs for the same product (e.g. PDF manual vs online help manual) – use DITA’s conditional text feature to clearly indicate which content should vary, and in what way.
  • Develop a glossary to precisely define terms, especially acronyms and abbreviations.
  • Consider using a controlled language (for instance, Simplified Technical English) with a limited vocabulary and fixed style guidelines. This will improve the consistency of your content and minimize the risk of ambiguity for localization service providers.
  • Use the SVG format for images that include annotations or callout text. SVG graphics are the easiest to edit with computer-assisted translation tools.

Following these suggestions from the start of a project will enable you to move seamlessly from the initial content creation to localization. And once the localization is complete, you will be able to use a DITA publishing engine to generate deliverables for each of your target languages with just a few simple commands. Authors simply have to create and follow well-defined layout rules, and DITA takes care of the rest.

An additional advantage to using DITA for localization is that after a topic has been translated once, it does not have to be translated again – reducing both cost and turnaround times in localization when content is reused.

 

Leverage the experts

Working with experienced specialists is the best way to guarantee a smooth DITA adoption and avoid localization complications. At Rubric, our experts know DITA inside and out, and they are ready to provide their best practice expertise to help you plan your DITA implementation strategy.

Send us some of your own collateral and we can advise on DITA best practices! After clicking, attach some of your source documents to your email and Ian Henderson, our CTO, will reach out with some tips and guidance to help you embed structured authoring and simplify your content management.

Stay tuned for the next couple of weeks as we cover Content Authoring, Product Information Management (PIM) systems and other topics that can help drive your localization strategy.


kenny-luo-1286691-unsplash-1280x854.jpg

Whether you’re dealing with an aircraft, an industrial robot, or a pump, when it comes to configuring and maintaining machinery there is no room for error. Mistakes during installation or servicing can lead to equipment failure, accidents, and even fatalities. That’s why it’s so important for technical documentation to be clear and concise, with no room for misunderstanding.

But achieving this level of clarity can be a major challenge, especially when you factor in language barriers: even though English is the prevailing language for technical documentation, engineers and end-users are not always native speakers.

Standardize and simplify

The proven solution to this problem is Simplified Technical English (STE). Originally developed for the aerospace industry, STE is a controlled language that utilizes a limited vocabulary where each word has a single, clearly defined meaning. By keeping word usage and linguistic construction simple and consistent, STE minimizes the potential for misunderstandings.

Today, STE is seeing growing popularity outside of aviation. In the manufacturing sector in particular, businesses and technical communicators are increasingly seeing the advantages of employing a preexisting, standardized framework for their technical writing. Internal style guides and glossaries are not new concepts, but developing them from scratch and keeping them up-to-date can be immensely time-consuming. In contrast, STE is a premade and proven system, and organizations can easily adopt it with just minor customizations to suit their industry.

But how can you tell if STE is right for your business? Well, consider this question: Is proper understanding of your installation and maintenance documentation critical to safety? If your answer is “yes”, then STE is almost certainly a good fit.

From simplified English to simplified translation

STE is an excellent way to make your technical documentation more consistent and easier to understand for non-native English speakers, but it isn’t always enough on its own. Sometimes you will need to go one step further and translate your content.

Target audience is the biggest factor here. If your end user doesn’t speak English at a high enough level, or at all, then translation is obviously the best option. This situation is especially common in B2C scenarios where the customer base is wider and potentially more varied.

When localizing technical documentation, STE still offers the ideal starting point, since the benefits of STE (reduced ambiguity, improved clarity and consistency) are passed on to the localized content.

By localizing your existing STE style guide and glossary for each of your target languages, you can maintain the same degree of clarity in your translations as you have in your source content. This approach reduces ambiguity from the localization process, minimizing the risk of misunderstanding or error and resulting in a higher quality, easy-to-use end product.

Additionally, authoring source content in a concise and standardized way will enable you to make the best use of translation memory (TM) technology. TM systems automatically provide suggestions to translators by remembering past translations. And when sentence construction, word usage and grammar are kept consistent in the source language, the potential for TM leveraging – and the resulting time and cost savings – goes up significantly.

Benefits for writers, readers, and businesses

Improved end-user safety is the main reason for adopting STE and standardized translations, but it is far from the only benefit. The approach we have described in this blog can make life easier for technical writers, translators, and customers, while also delivering considerable savings to your business., using the same controlled language across all projects makes content creation much more straightforward. With this methodology, technical communicators typically make fewer errors, spend less time worrying about word choice, and gain more benefit from TM systems – all of which help them to work more effectively and productively.

  • For writers, using the same controlled language across all projects makes content creation much more straightforward. With this methodology, technical communicators typically make fewer errors, spend less time worrying about word choice, and gain more benefit from TM systems – all of which help them to work more effectively and productively.
  • From the business perspective, STE keeps content concise and wordcount low. This leads to lower translation volumes and lower costs, especially when combined with improved TM system utilization.
  • Last but not least, implementing these standards will greatly enhance the consistency of technical documentation across your company as a whole. When instructions are always written in the same way, repeat customers will have a far easier time safely getting to grips with new products.
Partnering for success

Adopting STE principles in other languages can seem daunting, but that’s where Rubric comes in. Our expert team will work with you to develop bespoke localization style guides and advise on how to embed best practice terminology processes into your business.

Our experts can also help inform your decisions on the tooling and architecture used in your localization process. These choices will have a major, multiplicative effect on the quality of your content and the efficiency of your processes – so the earlier you involve us, the better!

If you’d like to learn more about STE or our localization services, we’ll be at the STC 2019 Technical Communication Summit & Expo in Denver, CO next week. Come visit us at Booth #304 from May 5th-8th – we’d love to meet you! If you aren’t in the Denver area, be sure to follow us on social media for the latest updates.


Follow Our Activity

Stay up to date with our latest activity relating to Global Content.