Sairam Venugopalan, Qualcomm
April 15, 2020

We’re increasingly being shrouded with the chime that ‘customer is king’, ‘customer satisfaction scores are pivotal’, ‘understand your customers in the same vein as you fathom your products’, and ‘engage more with customers for outside-in writing’. While all of these are critical for the success of user-facing product documentation, we have, at least, a couple of treasure troves, amidst the plethora of our day-to-day tools and practices, that we can cash upon. Exploiting those hidden reserves does not require separate company funding or extra-departmental budget allocation to improve customer interaction with the content we create.

If you’re gaping in wonder at what those unearthed troves are, test plans and technical-support cases are those buried jewels. As I mention these, you’d immediately quip, ‘These have existed for many eons since the evolution of my organization’s product. Don’t hoodwink me by presenting these items as wondrous wands or precious pearls.’. That’s where the bane is. Many a time, we’ve not harnessed these materials to their fullest potential. Although our eyes might have squinted at these items, at various points in the past, we might have bypassed them or dumped them aside without assessing the potency they wield.

How can test plans be helpful handles?

Test plans, and test cases to be more specific, are typically produced by the quality assurance (QA) or the testing and verification teams that coexist with most all product engineering groups. While a one-to-one mapping presents between a certain new feature or enhancement and a test plan, it is also possible that an array of features are sometimes recorded in a single test plan. This type of aggregation occurs when a set of features are allied and it makes sense to test them all in a single phase.

A test plan describes the hardware and software requirements for a feature that’s being evaluated. The number of devices, the specific software that must be running on these devices, and any pre-configuration to be performed before running the tests are enumerated in the test plan. Also, the interconnections or circuitry is represented pictorially, in the form of a network art diagram or a flowchart.

In a test plan, test cases are enlisted with unique identifiers and labels/descriptions. Each test case also contains the series of steps that must be performed to run the case, which is essentially a task or an operation that an end-user will perform with a product. In our technical communications parlance, each test case maps to a task topic that we might have authored for the product’s functionalities. QA personnel denote the success or failure of each test case.

As we look for sample scenarios that test plans offer, these might turn out to be real-life situations that can be transformed as an example to be portrayed. A use case or a configuration-example topic is prescriptive. It answers the question “How do I…?” It provides instructions on how to complete a common or helpful configuration task using real values. And, these are precisely what we derive from the test plans.

Besides being authored ‘in-house’ and accessible for all writers that are part of the product documentation team, these test cases are also reflective of environments or setups that mimic real-world conditions and production systems at customer sites. In such instances, the values that are entered for certain settings can even be simply copied and pasted into scripts or macros that customers maintain at their locations. As a result, customers can easily and quickly get their systems up and running.

What’s the deal with tech-support cases, then?

As writers, we can quickly relate to customer support, technical assistance, and systems engineering that we see in our cross-functional product teams across the organization. The cases or problems that are reported from customers are typically logged in a tracking database, such as Salesforce, ClearQuest, or ExtraView. The technical assistance engineer, typically, attends to these cases and resolves them in consultation with internal development, QA, or program management teams.

These cases are another source of wealth for writers to scour and scan for meaningful information that can be extrapolated as use cases or real-life scenarios in documentation. Several of these logged cases contain a rough sketch of a topology or a diagram that illustrates the environment in which a certain configuration or setup was performed. Logs or dumps of the different parameter values are also attached to the technical-support cases.

This data can be extracted and housed as configuration examples in our product manuals. Not only will such inclusion enhance customer experience, but it also vastly augment the depth and breadth of information that’s been covered in these documents. Many a time, a certain customer’s deployment might be so generic that it might apply to other users, too, and seeing information to this regard in end-user content satisfies their needs. Also, a sizeable optimization in customer-support cases can be witnessed.

A few tidbits to do the homework before writing use cases

When writing an example, many writers start by thinking “What feature do I need to document?” When you think about writing an example from this perspective, you are taking a software-oriented approach, and unless you expand your line of thinking, the resulting example might not be particularly helpful to customers.

The questions that follow help you think about how to create an example from a customer-oriented approach instead. They focus on how to write an example that provides a benefit or solves a problem rather than documenting an individual software feature.

Before writing a new configuration example, start by answering the following questions. These questions might also be useful for interviews with subject matter experts (SMEs), with whom you collaborate, to determine scenarios to author.

  • What issues do customers need to address? Use the answer to this question—not the scope of the feature—to determine the scope of the example.
  • What benefit is the feature supposed to provide to customers or the problem that the example is solving? Once you have determined the benefit that the example provides, make sure to include that benefit in the example’s title and introduction so customers can quickly determine if they want to read the topic.
  • In order to provide that benefit to customers, do you need to show how to configure several features, devices, or both together?
  • How does the use-case compare and contrast against any existing feature in my product’s application or a third-party vendor product? Does the example offer any significant advantage that outsmarts other existing features?
  • Is there a follow-on example or use-case that a customer will be interested to pursue after studying the use-case that’s currently presented? If so, that will form the Next Step and will be handy to be listed.
  • Can I look for sample scenarios that test plans, design docs, or tech-support cases can offer? These might turn out to be real-life situations that can be transformed as an example to be portrayed.

Cash into internal reserves, too, alongside customer feedback

As we continuously try to engage with customers to learn about their experiences with our information-products and improve their usability/accessibility, these types of engagements also involve dedicated efforts and additional costs, in some cases, if they’re not a part of your traditional documentation development activities. While it’s excellent to hear directly from our users and then adjust our content to meet their needs, this article was an attempt to open the windows into a couple of internal assets that most all product organizations possess.

Attempting to leverage the maximum out of test cases and tech-support cases can go a long way in buttressing content with use-case and scenario-based details. This method of supplementing existing documentation sets can be performed in tandem with other customer advocacy initiatives.

Sairam Venugopalan works for Qualcomm and possesses over 19 years of experience in writing and developing information-products for networking, telecommunications, and enterprise software. He has worked extensively on modular documentation and handled usability-enhancements of complex technical content