By Girish Hasabnis | STC Senior Member
Mark, a technical writer working on a suite of sophisticated medical imaging products, is often challenged to write the conceptual information for the product documents. Explaining the complex medical information to laboratory operators and clinical executives with little or no medical knowledge is very crucial. In this area, an error in understanding a concept can have serious consequences. Thus, Mark is always diligent in authoring the content. He thinks that if the readers know all the business scenarios, they would be able to use the product to its fullest potential. So, Mark always tries to find various approaches and methods that will help him explain the complex features with the use of real-life examples.
Many writers can relate to the example above. We as writers always use the famous WH-type questions (what, when, where, why, who, and how) to explain concepts. The techniques described in this paper can be used with WH-type questions to write about complex concepts easily.
State a Business Problem
Business problems or challenges help readers relate to a problem they face or a problem faced by someone else. This approach works best when the product or feature is newly introduced in the market.
Example
To explain the introductory information for a software product that is developed for the supply-chain management industry, you might use the following text:
In the globalization era, organizations endeavor to deliver the right quantity of products, at the right time, and at the right location. In order to achieve this timely delivery of products at the desired locations, organizations have to retain world-class services and fulfill customer needs. XYZ helps you solve the business challenges by:
- identifying the customers and their needs in advance
- coordinating with manufacturing facilities that are spread globally
- helping you plan delivery schedules in advance
State a Management Concept
Management concepts are the best tools to impart the practical knowledge and profound thinking that goes in the development of a feature.
Example
The following example demonstrates the use of this technique to explain the Graphs feature to its readers:
Graphs help you understand and compare the vital business information easily. Use graphs to analyze the health-related vital information of the patient visually. You can also understand various parameters of the patient’s health, such as blood pressure, WBC count, and so on.
Compare the Product with Another Product
Comparing a product with another known product helps you identify the differences easily and sets a frame in the reader’s mind about that product. One tip is to select the product that your reader is already familiar with. You can list the differences in a tabular form or in an unordered list.
In this approach, you can compare the product or the feature with:
- its competitor product (or feature)
- its previous version
You might use this approach to write white papers, training materials, or any knowledge-based documents.
Example
In order to emphasize a new feature that is present in the latest release of the medical software, you might want to begin as follows:
Starting with the sixth maintenance release of XYZ, you can view the medical information of multiple patients simultaneously. By viewing the medical information of multiple patients simultaneously, you can compare and analyze the medical data and perform benchmarking easily.
State the Benefits
Benefits help readers understand the importance of a product and how the product can ease their lives.
Note that benefits are different from features. A feature is a distinctive attribute or aspect of the product. A benefit is an advantage that the user receives or obtains by using the product.
Example
To explain the benefits of cloud computing, you might start as follows:
Cloud computing provides you with the following benefits:
- flexibility to meet business demands (for example, to scale resources up or down)
- reduction in expenditures on complex disaster recovery plans as cloud computing providers take care of most issues
- automatic software updates
- the opportunity to pay as you go, which reduces capital expenditure
- increased collaboration by allowing stakeholders to synchronize and work on documents and shared apps simultaneously
- the ability to work from anywhere as long as you have Internet access
Define and Explain the Feature
Explain the purpose of the feature so that readers can use that feature in a given situation. You might want to explain the validations and conditions of using the feature.
Example
The technique is explained with the help of a fictional mobile feature, Easy View.
Easy View is a friendly yet intuitive user interface experience with simple setup and core functions. You can turn the Easy View on in order to simplify the clutter of apps that always run behind the screen. You can choose the apps that you want to run in the background. Easy View also helps you view the most important information first.
Explain the Product and Its Components
Explain the core concept at first and then describe its intricacies. This approach can be used when the product consists of multiple components or modules.
Example
The following example is an excerpt taken from SAS Institute Inc. that explains its Base SAS product:
Base SAS provides a scalable, integrated software environment specially designed for data access, transformation and reporting. It includes a fourth-generation programming language; ready-to-use programs for data manipulation, information storage and retrieval, descriptive statistics and report writing; and a powerful macro facility that reduces programming time and maintenance headaches.
Base SAS includes these items: Procedures, DATA Step language, DS2 language, SAS FedSQL language, Macro facility, Output Delivery System (ODS), and ODS Graphics.
(http://support.sas.com/software/products/base/)
Give Generic Information First
Generic information sets a frame of reference in the reader’s mind. Specific information provides more data on the given subject.
Example
The following example is an excerpt taken from SAS Institute Inc. that explains SAS Management Console:
SAS Management Console provides a single point of control for managing resources that are used throughout a business intelligence environment. Rather than using a separate administrative interface for each application in your computing environment, you can use SAS Management Console’s single interface to perform the administrative tasks required to create and maintain an integrated environment across multiple platforms. SAS Management Console enables you to manage
- server definitions
- library definitions
- user, group, and role definitions
- resource access controls
- metadata repositories
- job schedules
(http://support.sas.com/software/products/sasmc/)
Explain the Most Significant Information First
The most important information sets the context for the reader. After providing context, then explain the rest of the information.
Example
The following example is an excerpt taken from SAS Institute Inc. that explains the most important concept first and then the rest of the information to the system administrators:
An authentication domain is a name that facilitates the matching of logins with the servers for which they are valid.
Note: This matching is not important when you launch a client, but it is important when you access certain secondary servers such as a third-party DBMS or, in some configurations, a standard workspace server.
Each user ID and password is valid within a specific scope. For example, the user ID and password that you use to log on to your computer at work are probably not the same as the user ID and password that you use to log on to a personal computer at home. It is also common for database servers and web servers to have their own authentication mechanisms, which require yet another, different, user ID and password.
An enterprise application that provides access to many different resources might require that a user have several sets of credentials. Each time a user requests access to a resource, the software must determine which credentials to use to provide access. The software could challenge the user with an interactive prompt for user ID and password, but that quickly becomes an annoyance that interrupts the user experience. The software could randomly try different credentials until it finds a set that works, but authentication attempts can be expensive in terms of performance. In the SAS Intelligence Platform, the software attempts to use only the credentials that it expects to be valid for a particular resource or system.
The software’s knowledge of which credentials are likely to be valid is based entirely on authentication domain assignments. For this reason, you must correctly assign an authentication domain to each set of resources that uses a particular authentication provider, and also assign that same authentication domain to any stored credentials that are valid for that provider.
Use Progressive Revelation or Sequential Disclosure of Information
Explain the concept as it is happening so that it will unfold in a logical sequence. This approach helps you construct the building blocks in the reader’s mind so that they understand the concept easily. This approach can be used to explain the workflow of using a product or to explain a process.
Example
The following example is an excerpt taken from SAS Institute Inc. that explains SAS Cloud Analytic Services.
What Is SAS Cloud Analytic Services?
- SAS Cloud Analytic Services is a server that provides the cloud-based run-time environment for data management and analytics with SAS. By run-time environment, we refer to the combination of hardware and software where data management and analytics take place.
- The server can run on a single machine or as a distributed server on multiple machines. The distributed server consists of one controller and one or more workers. This architecture is often referred to as a massively parallel processing architecture. For both modes, the server is multi-threaded for high-performance analytics.
- The distributed server has a communication layer that supports fault tolerance. A distributed server can continue processing requests even after losing connectivity to some nodes. The communication layer also enables you to remove or add nodes from a server while it is running.
- SAS Studio provides a programming environment for developing and submitting programs to the server.
You can add many more techniques to the above mentioned list to further simplify the process of writing concepts. These approaches help you identify the patterns, bring more clarity in the concepts, and save you writing time.
GIRISH HASABNIS (girishhasabnis@gmail.com) is an STC Senior Member and a technical communicator at SAS Research and Development. He has more than a decade of experience working on several projects from various industries including supply chain management, telecommunications, healthcare, banking, electronic design automation (EDA), geographical information systems (GIS), and global positioning system (GPS). He enjoys producing audio-visual material (eLearning and how-to videos for products). The series of how-to videos that Girish produced and published on SAS’s YouTube channel is very popular and has more than 8,300 accumulated views.
