Turning technical documentation into a valuable asset

As a tech writer for more than two decades, it still amazes me to see the gap between the potentiality and the reality of technical documentation.

In recent years, I have been pondering how technical documentation in the high-tech industry can bring true value to the product instead of being a mere appendage. 

Having experimented with a few products, the outcome convinced me of the worth of this direction. Since then, I’ve been looking for opportunities to try out the idea further. Now, after six months as a technical writer at DoiT, I’m going to share some lessons I’ve learned and some new thoughts. 

First things first

Technical writers are almost always a later addition to the engineering or product team (depending on the organization’s perception of how to develop a product). After all, in the current era, everyone is a writer/publisher. When you are still at the stage of finding early adopters, GitHub repositories, blog posts and forum discussions may be more cost-effective to reach the target audience.

It’s only when the product has passed those early days and is ready to scale that someone might suggest bringing in technical writers. From my experience, the first thing those technical writers need to do is establish the ground rules, using conventions.

It might feel strange to put conventions in the first place when talking about an industry that boasts innovation and creativity. However, conventions are not the enemy of innovation or creativity. Following conventions on the non-critical path can reduce cognitive load and thus help people focus on critical tasks.

Conventions in technical documentation come in different forms, for example,  a comprehensive style guide (Google developer documentation style guide, Microsoft writing style guide) or a simple set of rules (AWS document conventions).

You do not need a perfect style guide before working on the documentation. A more effective approach is to build it up while familiarizing yourself with the product. In other words, do it during your onboarding days. 

Here are the steps to take during this phase:

• Pick up the fundamentals when doing the basic clean-up:
  • Are headings and titles using sentence case or title case; are they using the gerund (-ing verb) or base form verb?
  • Are procedures written in numbered bullet points or as a long narrative?
  • Is there a strict rule regarding serial commas (a good topic if you want to start a debate among writers)?
  • How are UI interactions described, for example, does a user “click”, “select”, or “choose” a button?
  • How are screen captures taken and rendered? Call-outs?
• Build your in-house style guide along the way:
  • Cherry-pick from industry standards and adapt to your own needs.
  • Understand that it’s a living document, expecting new usage and novel terminology.

An in-house style guide is a fundamental part of technical documentation. It not only helps you scale your team of writers but also gives guidance to others in your organization who need to write technical information, whether a draft for technical writers or a blog post. 

You might also uncover topics of more significance along the way, for example:

• How conversational/personal is the overall style?
• How videos are used?
• How sensitive information is handled?
• Who are the stakeholders or active contributors to the technical documentation?

Don’t be surprised by your findings. 

Design of technical documentation

Technology products are complex. They not only use complicated technologies but also interact with other technology products, often by other organizations.

How do you tackle this complexity when writing technical documentation?

A common answer starts with: “It depends.” Nevertheless, we do have two powerful tools at our disposal: framework and conceptual model.

Framework

A framework in technical documentation can be a template or conceptual structure that facilitates the writing of individual topics (that is, topics that do not relate to other topics).

Most blog posts and single pages of technical documentation are focused on individual topics, and thus can benefit from a well-defined template or framework. 

Are you going to write an installation guide? 

Think about a three-part structure: prerequisites (including hardware and software requirements), execution (the actual steps of installing the subject matter) and verification (check the version, run a hello-world example, etc.).

Are you assembling instructions to query some data?

Make sure to include required permissions, example queries and a detailed explanation of input and output.

Even if there is no available template, with some practice, you can develop a framework with relative ease. Before joining DoiT, I wrote a blog post named How to write (and rewrite). The approach suggested there mainly relates to the construction of a framework. 

Below are the key points:

• Use the Minto Pyramid Principle® to expose the underlying structure of a complex text
• Create visual hierarchies to help the audience navigate the complex
• Devise buckets to support the user journey

Conceptual model

The complexity of technology products results largely from interactions, either between components in the same product or between products in the same business/technology landscape that need to work together to form a full solution.

You usually do not expose the complexity inherent in the product. Your secret sauce could be interesting to your rivals but not necessarily to your customers.

You do need to pay close attention to the complexities that may cause external friction. They are often the culprits that stymie your customers and even your own support team.

In his acclaimed book The Design of Everyday Things, Donald Norman explains that providing a good conceptual model is the most important principle for taming complexity. I agree with this wholeheartedly.

Let’s take a closer look at how to leverage the conceptual model in technical documentation, using two examples from the DoiT Help Center.

Building block features

When referring to the Attributions feature, DoiT product marketing manager Matan Bordo likes to say that it is “one of the DoiT Cloud Management Platform’s stickiest features when used correctly”. If you draw the conclusion that it’s not easy to take full advantage of this feature, we hear you.

Attributions is a building block feature. Like many other building blocks, it achieves little by itself. However, once you grasp its essence, you’ll have fun working with it.

In a recent update, we revised the documentation of the feature and put the scenarios at the beginning, to help the users establish what it is capable of before leading them into all the nitty-gritty of configurations.

Ecosystem plugin features

In September we added an article called Visualize with Grafana Cloud (contributed by our CTO and co-founder Vadim Solovey). As you may know, Grafana is not a solution by DoiT but a popular service in the Cloud Native Landscape. 

Similar to the building block feature example, in the Introduction we established the rationale of the integration and in which aspect this integration could benefit a business running on the cloud.

Whether in the product or in the ecosystem, a good conceptual model depicts the relationship between interacting components, thus helping users navigate the domain they choose.

Other benefits? One thing you can be sure about technology is that users are creative when it comes to using technology to solve their problems. With a proper conceptual model, your users will discover use cases for your product; better still, they’ll become your voluntary evangelists and help you to improve further.

It’s teamwork

So, where are we now?

Conventions and frameworks can be handled with generic technical writing knowledge (therefore a good starting point for new hires or junior writers), while building proper conceptual models at different levels require deep knowledge of the product.

DoiT is a technology company that takes pride in its deep cloud expertise and customer-centric mindset. The learning environment is superb. Topics discussed in internal Slack channels and shared on internal wiki or StackOverflow are rich in knowledge, and people are eager to share what they know, help each other out and collaborate to get better, both individually and collectively.

Being part of the multidisciplinary product management team, technical writers are thought partners to product managers and designers. The ability to write clearly is based on the ability to think clearly, which is of great value when it comes to surfacing assumptions and modeling product features. 

When discussing what the technical writing team wants to achieve, we set our vision to make the technical documentation a valuable asset in DoiT product portfolios. The key here is teamwork. Quality technical documentation is not a lonely task for technical writers, but an endeavor the technical writing team at DoiT takes the lead on and works with the whole organization to deliver.