Technical Communication in the Storage Management Industry

By Suvarna Inamdar and Jayanthi Krishnan

Information technology today has a firm foothold in organizations worldwide. With the amount of data generated by businesses growing every year, managing this data is absolutely critical for any organization to function smoothly. This brings into focus the importance of storage management. Considering today’s economic situation, utilizing existing resources optimally and managing the huge amounts of data, is a big challenge. The colossal scope of the challenge is evident in mission-critical applications where the availability of data and applications must be 24x7.

Some examples of businesses that generate colossal amount of critical data are stock exchanges, multinational banks, railways and airline industry, and medical facilities. Some other examples of businesses that generate vast amounts of non-critical data are educational organizations, online search engines, and Internet shops. A key requirement for many business concerns today, is effective and efficient management of massive volumes of information, present on a wide range of hardware devices representing a heterogeneous environment[1]. Customers today demand quick and easy access to real-time data. To meet this requirement, the storage industry is making veritable contributions towards  providing data availability and managing this data.

Some of the important challenges faced by the storage industry are:

• Increase in data generated by 2003 is approximated at 1Petabyte (PB)[2].

• Need for storage products to work in a heterogeneous storage environment.

• Increasing customer requirement for standardization of products. Global bodies like SNIA are contributing in a big way towards standardization of storage products.

• Need for products to provide quick and efficient disaster recovery; 9/11 has already emphasized the importance of disaster recovery.

• Demand for efficient and powerful management tools that effectively reduce the cost of storage management.

• Interoperability and virtualization across products from different vendors.

• Need to keep pace with growth in information exceeding 50%-70%, while saddled with growth in storage exceeding 100% per year.

Gap between the requirement for storage and the supply from the storage industry. Proactive measures are required to bridge this gap before it becomes unmanageable.

Meeting the Demand for Storage

The storage industry has taken the following steps to meet the challenges:

• Improve quality of products, increase productivity and investment in research and development activities.

• Focus on re-organizing staff for optimum performance.

• Develop tools to automate processes, standardize products, provide complete storage solutions to businesses.

• Improvise products to enable them to monitor and optimize application performance dynamically and provision hardware resources automatically to meet changing demands.

• Offer better service and processes in system integration, installation and startup services, migration, support, maintenance, and cross-product compatibility.

• Be well informed about the competitive products in the market.

Communicating with the User

With so many challenges to face and stiff competition to consider, the availability of correct, complete, and well-documented information on the various features and usability of products is important. The kind of documents generated by this industry are similar to those in many other industries. However, since the products are quite technical, the documents play a major role in communicating multifarious tasks in simple terms.

There is a wide clientele for storage information. These could vary from the interested onlooker, to a technically sound engineer, the end user of the products, customer support, product analyst, stock market executives, or even competitors. The information is available on different media and in various formats. However, for the purpose of this article we will focus more on end user requirements where the end user is essentially someone who uses the product, interacts with customer support or the sales and marketing personnel. The classification of user documentation at a high level is as follows:

• End User Documentation

• Engineering Documents

• Customer Support

• Sales and Marketing

End User Documentation

This category would generally include users who have already bought the product and want to use it. They could either be technically savvy customers, or absolute novices whose focus is to achieve the end result of managing and storing data using the product. It could also include users such as administrators, who are generally responsible for administering storage for the company.

Some documents are targeted for advanced users. These users are responsible for tweaking the product to suit the company’s requirements, or to make the product work with the company’s existing products. This could be done using specific tools provided with the products.

End user documents include:

• Release Notes and Readme

• Installation and Configuration Guide

• Administrator’s Guide

• Command Reference Guide

• Online Help

• Hardware Compatibility Document

• Troubleshooting and Error Message Guide

Release Notes and Readme: Release Notes and Readme inform the user about the new features and functionality or feature enhancements, if any. These documents may also contain brief information about where the various required files are located. Readme is generally a plain text document and consists of information that you must read before installing the product.

Installation and Configuration Guide: The Installation and Configuration Guide provides steps for installing and configuring the product. Storage products are complex and tightly bundled with the operating system (OS). Configuring the product requires OS familiarity and is often done by an administrator. The steps that this document provides must be accurate and tested for correctness. Product upgrade information is also provided in this guide.

Administrator’s Guide: The Administrator’s Guide provides the system administrator with complete information about the procedures and concepts involved in using the storage management product. This guide attempts to describe the product architecture in detail with proper illustrations and diagrams. It focuses on providing the user with insight into the administrative tasks and the internal functioning of the product, and lists useful examples, best practices, and ideal scenarios for reference.

Command Reference Guide: This document covers the complete command line functionality that is available with the product. Frequently used commands are listed in the Command Reference Guide, which can also be used as a quick reference guide. It complements the command line help.

Online Help: Online help is a browsable context-sensitive help system bundled with the product. The help system is developed in a format that considers factors such as product platform, product interface, OS compatibility, and browsers supported. For example, a product with a web interface may have a web based help system.

Hardware Compatibility Document: A Hardware Compatibility document gives the administrator ‘what-works-with-this-product’ information. Organizations may have a heterogeneous hardware setup that may require close monitoring of compatibility issues. The hardware compatibility guide provides the user with all kinds of hardware configurations that are supported with the product, details on setting up the hardware configurations, and hardware connectivity information. This document contains highly technical information, and requires the writer to be aware of the various technicalities involved in the hardware setup. The information must be tested well, in all kinds of adverse scenarios.

Troubleshooting and Error Message Guide: This guide describes the problems the user may encounter while working with the product, and a workaround for those. It also has detailed information on error messages displayed by the product, and the relevant corrective actions.  These are very important documents for users such as customer support and administrators. It is therefore the technical writer’s responsibility to ensure that these documents are written with in-depth understanding of the product. The documented error scenarios must be properly tested.  Appropriate references to steps in the process when some error might occur, must be well explained. The error messages covered must be informative and useful, and must lead the user to resolving the error situation. If an error message lacks clarity, the writer can suggest appropriate improvements to the engineers.

Engineering Documentation

Engineering documents are used internally for reference by engineers. These could also include papers published to external users to communicate new ideas. Engineering documents include:

• White Papers and Reference Papers

• Application Program Interface (API) Documentation

• Software Development Kit (SDK) Documentation

• Product Integration Documentation

• Technical Bulletins

White Papers and Reference Papers: White papers are documents that provide an overview of new technology or products, its uses and feasibility, and implementation of the new products. With the Internet becoming one of the fastest and easiest modes for distributing information, white papers have become a standard way of communicating in-depth information to an interested audience. They communicate information in terms of problems that the new product solves, which often serves as a key factor for a purchase decision.

Application Program Interface (API) Documentation: APIs are a set of functions, protocols, and tools for building software applications. They provide all the building blocks that a programmer puts together. Most operating environments provide APIs so that programmers can write applications consistent with the operating environment. Technical writers create API documentation that provides the user with detailed information about API functions, their usage, inputs required by the functions and parameters to be passed along with adequate examples.

Software Development Kit (SDK) Documentation: SDK is a programming package that enables a programmer to develop applications for a specific platform. Typically, an SDK includes one or more APIs, programming tools, and documentation. SDK documentation describes how to use the SDK.

Product Integration Documentation: Different storage products bought from the same company must work in tandem. Also, if there is an agreement with other manufacturers to use their product, these products should work seamlessly. The product integration document should contain  information on how the product is integrated with other products and key information points that enable these products to work together. For example, if a company sells both storage and backup products, these two products should work smoothly together. In such a situation an integration document would specify the finer details involved in integrating the two products.

Technical Bulletins: These documents are intended to provide easy-to-read, but detailed instructions on installing and using the product. These give an update on the product features and hot fixes. Technical bulletins are also used to communicate updates on the latest technologies.

Customer Support Documentation

The documents that fall under this category are mainly the troubleshooting guides, error handling guides and also training guides. Some of these documents have already been discussed under End User Documentation. The type of documents they refer to depends on the kind of support call they need to attend. Following are a list of some additional documents they use.

Customer Support documents include:

• Training and Education

• Partner Training

• FAQ

• Knowledgebase

Training and Education : After the customer buys a product, the storage company is expected to provide in-depth training on using and managing the product. Apart from this initial training, storage companies also conduct frequent instructor-led classes to help customers update their knowledge and brush up on specific product features. Training must also be given to customer support engineers. Technical writers are involved in developing the training material for the product.

Partner Training: Strategic partnerships are fast becoming one of the most accepted ways to expand the scope of products and market share. These alliances benefit the partners as the resources are shared and investment and risks are divided. Training helps evolve the partner relationship.

FAQ: FAQs offer a quick look-up for customers. These are generally hosted on the company’s web site. This site offers answers to common problems that a customer may have.

Knowledgebase: A knowledge base is a repository of product related information. Customers can look up this site for answers to questions that have been asked earlier. The site has an efficient search engine.

Sales and Marketing Documents

Sales and marketing teams also refer to the documents discussed in the preceding sections. In addition, they also use various types of marketing and sales literature. Technical writers can contribute to developing marketing and sales literature.

Internationalization and Localization

Technical writers must consider ease of translation while writing product documentation. Considering that storage stretches across global businesses, it is necessary to address internationalization and localization issues. Companies are under increasing pressure to release products in different languages. With stiffer competition in the storage products market, product cycles are growing shorter, and products are updated almost until the last minute. It is therefore necessary to maintain modularized and tightly-integrated documentation content so that changes can be made even after the documentation is sent for localization.

Recommended Profile of a Technical Writer

The products in the storage industry are highly technical and complex. These require the writer to be technically sound. Some criteria that a storage company would look for in a technical writer are:

• Engineering background (preferred).

• Proficiency in English.

• Good level of system administration knowledge of the OS.

• 2-3 years of experience in writing for technical products.

• Quick grasp of new technologies.

Jayanthi Krishnan is Senior Technical Writer with VERITAS Software. You can contact her at contactjayanthi@yahoo.com. Suvarna Inamdar is Senior Technical Writer, VERITAS Software  and Vice-President India Chapter STC. She can be reached at  suvarnai@yahoo.com.

STC India | Home | Contact Us

Copyright © 2003 India Chapter STC. All rights reserved.