How authors transform complex concepts and terminology into clear content

As Technical Authors, our job is to describe products to end users, whether that is Engineers or every-day users. The documentation we create must describe the product and its features accurately, while also being easy for the reader to understand. To do this, we must first fully understand what the product does and what the user can do with it.

Products can be complex for many reasons, for example:

• The product is specialized and requires certain training
• The product requires a thorough understanding of its application
• The product has variants, each with its own requirements for specialized knowledge

Many times, these complexities affect the regular operation or use of a product, leading to product documentation that is overly complex and hard to follow. In other words, the product documentation describes “how it works” instead of “what can be done with it”.

Technical Authors need to understand complex products and their processes in order to correctly document them.

How do Technical Authors understand products?

Engineers and product owners understand the product they are offering to the last detail but, as I’ve already said, not all information is helpful and, in some cases, it can even be counter-productive to include. Technical Authors stay focused on the audience who will use the product and what that audience needs to know, rather than technical details that aren’t useful to them.

That’s why we learn about the product by experimenting with it, learning about its users, and asking experts questions, such as:

• The functionality of the product
• The product limitations
• The uses by different audiences
• If the product can be configured differently for different users
• If the product has specific requirements, such as hardware or software requirements and licenses
• If users are required to have certain knowledge

When taking a first look at a new product, we usually get an idea of the purpose behind the product, who it’s aimed at, what problem it’s meant to solve, and have a scoping session, where the product Engineers explain the product itself to us.

If possible, we ask for a demo or a copy of the product so we can interact with it and discover more. Otherwise, we analyse the documentation that is already available and connect the dots with what we’ve learned in the scoping session and any other input available.

As technical authors we have a different perspective from Engineers, who are often too close to the product to fully understand how to communicate the correct information in the correct way to the users. By using the product and reading any existing product documentation, we can work together with Engineers to either improve or craft documentation into something much more rich, useful, understandable, and that can be shared with a wider audience.

The analysis and design process

Before we begin to write about a product, we go through steps to understand the documentation needs and make a plan for our work. To do this we:

1. Understand the customer’s request, providing background information of the customer’s situation and requirements
2. Review the materials provided by the customer
3. Identify the required deliverables
4. Identify project requirements and constraints
5. Set timescales, significant events or deadlines
6. Create an information model and content plan

Transforming the content

After we have a solid understanding of the content and have set all the initial preparations, we are ready to use tools to aid us in transforming the content. There are many approaches we can take towards this objective, for example:

• Summarizing content in simplified user interface images
• When not necessary, replace images with text
• Reducing the number of words used, to form small, clear procedures
• Style the content text, such as headings, paragraphs, and tables
• Use ordered lists or bullets instead of chunks of text
• Reuse content using snippets
• Use localization-friendly language
• Use conditioning, that allows us to choose the content we publish for each platform

We can adjust the tools we use and the way we use them for each client and product.

Collective knowledge

Our Technical Authors come from a range of academic backgrounds in languages, humanities and sciences. This means we can form internal teams who not only understand the product but more importantly understand the users, their information needs, and how they access information. This in turn means our teams know how to create documentation that best meets these needs.

At 3di, we already work with companies that come from different backgrounds and have complex products, such as Tekscan, Expel, and Anybotics; therefore, we don’t start from scratch: we know what to ask and how to work with different products and audiences, and solve challenges.

Our extensive experience working with companies in different industries also means we know what standards and regulations the documentation must meet.

You know your product and users best – we want to help you transform your knowledge into clear information so that your customers get the best out of your product, for their benefit and yours.