How to Channel the Knowledge of Technical Experts into Perfectly Crafted Content

Over the years, technical writers evolved to be more than just writers. They are now being asked to provide a strategic value-add by structuring technical content and optimizing its delivery to users.

This change occurred as subject matter experts began to play a central role in the technical documentation writing process – a role that comes with challenges since most SMEs have no background in technical writing. Learn how SMEs can overcome these challenges and how IXIASOFT’s technological partnership with Congree can help simplify their contribution to content.

The History of Technical Writing

Technical writers were not always responsible for creating technical documentation. In fact, before this role emerged as a distinct profession, subject matter experts (SMEs) used to write all manuals. Here’s how it all started:

From the late 19^th century to the early 20^th century, technical documentation was known as a “cottage industry.” Manuals were created by experts, for experts, and were neither accessible, nor comprehensible by a broader audience.

The discipline of technical writing gradually appeared with a growing non-engineering audience. English professors became its first instructors, teaching engineers to document their inventions more clearly.

World War II then marked an increased demand for consumer goods and military equipment that prompted non-SME writers to enter the mix. It was now essential to deliver technical documentation that was readable by everyone. Technical writers were born.

Why Are SMEs Increasingly Called Upon to Contribute Content?

The job of technical writers includes interviewing SMEs, obtaining and writing information about a product, and editing content from experts.

With technical writing being recognized as a formal discipline structured by college and university courses, subject matter experts tend to have little to no experience in this field.

Paradoxically, they are increasingly being asked to contribute content. This is mostly because the advent of agile documentation processes in small software development teams means that in some circumstances, SMEs are required to write content – a contribution facilitated by CCMSs such as MadCap IXIA CCMS.

In parallel, the role of technical writers is evolving. Over the past seven years there have been fewer “technical writers” job listings in the US, and more content strategist, information architect, and technical content specialist positions. Such a shift suggests tech writers are slowly losing their primary redactors’ place to an editorial role. Technical communicators – a designation that is more inclusive of these recent job titles – work to structure technical content and come up with the best ways to deliver it to the company’s user base.

Authoring using DITA is gaining popularity among technical communicators to meet this objective. However, SMEs are more often than not reluctant to learn DITA. Thanks to CCMSs such as IXIA CCMS Web, this is no longer a requirement as the system hides DITA complexity.

What Challenges Are SMEs Encountered With When Writing Technical Documentation 

There are additional challenges SMEs cannot easily avoid.

1. Content needs to be reusable

SMEs must be able to identify the content they can reuse and have to write content while keeping reuse in mind.

2. Content needs to be translation ready

Content should be concise and consistent to facilitate the translation process. Minimalism should be favored – a principle often hard to digest for SMEs, who could think that the more material the better.

3. Content has to fit the brand messaging

The technical documentation created should be consistent with the message the company wants to send its audience. This includes using the appropriate terminologies and tone of voice. These elements will help build a strong relationship with customers.

As opposed to technical writers, subject matter experts do not always have access to these guidelines, or they do not know where to find them. This explains why content created by SMEs needs to be reviewed by technical writers before publication.

The Benefits of Working With a Living Style Guide

In order to enhance SME contribution to content creation, it is critical to assist them with a set of rules.

First, by maintaining a style guide.

• Defining a tone and what emotion you want to evoke (trust, security, happiness)
• DOs and DON’Ts (grammar rules, spelling, sentence length)
• Define rules for content reusability

Then, maintain a terminology database

• Define words to use and words not to use
• Define a unique meaning for every technical name

Once these rules are in place, it is important to ensure SMEs actually follow them, otherwise the time and effort invested in their creation would have been a complete waste.

This Is Why Congree Exists

Congree is a tool that works in confluence with IXIA CCMS Web. This tool knows your company’s entire style guide, regardless of the format it is written in (PDF, confluence page, written form).  It also knows your entire terminology.

With this information integrated, Congree can advise users in real-time if any of the content being drafted contradicts the styling guide and/or terminology database of the company. It also features detailed information about what the user should do next, explanations on what is wrong and how it could be done correctly, and improvement suggestions, which makes it living and interactive. The tool is equipped with an indicator of the quality level of the documentation according to the guidelines that evolve as you go.

As they step up into their role to contributing more content, subject matter experts need guidance. This frame can be materialized with a style guide and a terminology data base. But those can’t work if SMEs won’t follow them. With the Congree tool, this could not be a concern anymore.

This blog was originally presented as an IXIAtalks webinar by Philipp Baur, Keith Schengili-Roberts and Sydney Jones. You can find the webinar here.