Monthly Archives: January 2021

Technical Writing in the Near Future

At an interview, a product manager asked me “what it is the future of technical writing?” I found it difficult to quickly answer this rather open-ended question. Though unable to recall how I answered it, I recently thought about the question again.

Without a doubt, game-changing developments in the software field will change technical writing in the future. But based on today’s technologies what will we be able to see fairly soon?

Text Will Become an Option

Where using products becomes intuitive, text may be optional. Thus an interface may no longer need explaining. Text is also misunderstood in different instances. In turn, this can affect the quality of translations.

However, text will continue to pervade in technologies that needs explaining, especially those that are emerging.

Steps as Infographics

Infographics will probably become more common when conveying procedural information. During the Covid pandemic, I’ve seen infographics warning people about protecting themselves; which has made me think of our reliance on infographics to explain procedures. Here is an example infographic from the World Health Organisation.

The presentation of steps has evolved over time. In the late 90s, procedures consisted of many steps and sub-steps. In recent years, step have become less rigid, allowing scope for creativity. Thus numbers are often presented as attractive icons alongside images.

Animation

Animation may replace the use of screenshots and static diagrams. Animation is starting to appear in documentation in SVG format (see Ox.org – a platform for Ethereum). This is no surprise given that we are consuming more animation content than ever before.

For example, Cocomelon – Nursery Rhymes was ranked in 2021 by Tube Filter as the 2nd most viewed YouTube channel with over 761 million weekly views. There has also been a huge increase in animation-based explainer content on YouTube. Personally, I found animations on YouTube very useful when learning new technical concepts.

Through a set of animation elements, it is easy to turn an SVG image to animation. Javascript libraries are readily available to animate SVG files (see 8 Javascript Libraries to Animate SVG). But expect more animation options to exist in the future, and we may no longer need the assistance of web designers.

Video Video and More Video…

We often produce video to describe interfaces or concepts. Video is likely to become more common in documentation as video editing technologies become easier to use. For example, recording screen shares in Microsoft Teams is simple, thus allowing quicker creation of content to describe user interfaces. Just like a film offers another dimension over a book, a video is an exciting alternative to text-based user guides (see Exploring the World of Video Guides).

In the near future, video collections are likely to be closely integrated with help center content. Some companies maintain a library of videos on YouTube, e.g., Salesforce. However, the text-based content of a help center/documentation site and a video channel is still largely separate.

User Assistance Text

Text will become even more integrated with the user experience of a product, where we could view content before clicking on a link or downloading a user guide page. User assistance text will instantly give you answers to questions of what the feature is and how and why you would use it. In this example, users can open a mobile app and find out how to use it for editing.

How the text appears depends largely on the design of the app. Text may appear directly in the UI, as pop-up text, or within “empty screens”.

In more ways than one, companies could both gain business and save money with user assistance text:

  • Customers could try out a product without the support of a sales representative, allowing them to get started quicker.
  • Customers would be less likely to call support.
  • The production costs of the documentation would be integrated with those for front end development.

In Chris Stokel-Walker’s article on Increment, Sara Feldman from MindTouch mentions that “Documentation becomes relevant far sooner in a customer’s journey than it used to. In fact, it becomes relevant at the very, very beginning of a customer’s journey, whether that’s automated or with a human.”

Authoring software will become better for creating and managing user assistance text. Managing user assistance text is already possible to an extent with some packages. MadCap Flare allows the integration of micro content, which is summary information that appears when searching within a help centre.

Chatbots

Technical authors will be able to further integrate their content with chatbots. Many technical authoring principles, such as topic-based writing and structured content, can be applied to chatbot design. Chatbot design may even become part of technical authoring, while engineers will take care of development.

Transcribed Content

With video becoming more common, the alternative “text form” user guide could even be a transcription of the video. Presently, there are various apps that generate transcriptions when a user pays a certain amount per minute, or pays via flat monthly fees (see this Techrepublic article). Good quality and feature rich transcriptions are likely to be available in the future.

Audio User Guides

There is a use case for audio user guides catering to visually impaired users. Some public places currently use NFC (Near-Field Communication) for connecting to audio guides. The Informaze blog mentions about using this technology within churches in Milan. RSF International provide technologies for audio guides in tourist locations.

Moreover, learning through podcasts has become increasingly popular. The PlayerFM site lets you acquire knowledge of all sorts of things. Audio guides may help users that have a distinct preference for audio learning, especially conceptual information that does not require interacting with a user interface.

More Legacy Content in HTML or PDF Form

Lastly, we will see more legacy content available in print or web form that that never previously existed. Think of vital documents that have been stored in filing cabinets for years. Publication technologies will enable legacy content to exist as PDF manual and/or HTML pages, albeit with access control. For example, consider a user guide with information on nuclear waste content that only needs to be available for specific users, but has to be accurate. While newer content will exist in the latest forms of video and maybe even animation, such timeless content may not be superceded.

Happy Writers and Unhappy Customers

This could be a common situation when customers are consuming your documentation. You’ve produced good work in researching the product, creating a blueprint, applying the writing style, and getting comments from developers. Your JIRA tasks met sprint objectives and were done in time.

Why Could Customers be Unhappy?

Unhappy customers may not be because the content is poorly written or is accurate. It may be because they have had problems using the documentation.

But Your Documentation is on a Website!

Your documentation is available to all from a website. You’ve picked a documentation tool that has effective templates, is easy-to-use, and fits nicely with the technical requirements of the software (e.g. it is a jamstack solution that uses static site generators). No matter how well-implemented or attractive the documentation appears in its design, it still doesn’t help the needs of the consumer.

Customers Still Call Support

When customers have no time, they would rather call support than read through the content. Even if the content is rich and informative, it may not help in certain situations. They may try to call support even though the documentation is there. Moreover, your company may have dedicated support channels, and they know who to call.

Understanding the Customer Journey

Whether or not a customer reads the documentation, their journey starts when they arrive at your site. They should be able to make a decision from the home page as where to go next. Normally, this is through a search or via the navigation menus.

Short Form vs Long Form Content

Short-form content gives the customer a brief synopsis of the product or functionality, allowing them to understand the product and make decisions on what to read next.

Long form content is information in more detail, covering procedures, reference material, and further concepts.

Both forms of content go together. Users may stop after reading the short form content. That’s great if the short form text provides all the information they need. Or, they could venture further in to the long content.

Search

Many users explore the documentation from a search. Therefore, ensuring that the pages are findable from their keyword combinations is key. If your site is implemented in MadCap Flare, you can configure search by setting up various search tags. But if your documentation site links to a provider like Algolia, setting up search is almost automatic.

Navigation Menus

There are many ways to design navigation menus. While a left-hand menu bar is common, there are documentation sites with additional navigation menus in the main pages. This design exists in the Spotify help centre and the Akash Network. An over-crowded left-hand menu bar alone can make a site hard to navigate.

Organising the Pages into a Logical Order

Once customers know where to go, organising the pages in a logical order is essential for completing their journey. Depending on how they use your content, there may not be a complete right or wrong answer. For example, one helpdesk team informed me that typical customers would be less likely to read conceptual content before doing the steps. This differed from my own learnings of the product, and the initial feedback that I received.

Defining Quality

Lastly, improving the documentation to help customers should be part of a definition of quality. In her presentation at Write the Docs Prague in 2016, Riona McNamara from Google explains that quality in technical documentation can be defined as either Functional Quality and Structural Quality (see As Good As It Gets: Why Better Trumps Best). Structural Quality focuses on the immediately tangible areas that make documentation quality, e.g., the way it is written and laid out. Functional Quality, on the other hand, is whether the documentation achieves what is supposed to do.

In short, you could consider these two definitions in your plan to improve the documentation and make customers happy.