Liang Qiuxia, Cheng Haitao and Yi Hong, Huawei Technologies Company
Reprinted with permission from Huawei Technologies Company
Our growing market share, the increased number of product variants and the shorter period for product release force us to produce more content in a shorter period of time with limited resources. Besides, customers require that documentation is task oriented and that the help information is correct, complete and relevant to their customer orders.
This article presents a task-oriented and modular design approach that provides a more reliable and scientific way to design documentation, enhances the efficiency of documentation development, and ensures a quick response to documentation customization.
Huawei is a leading telecom product and solution provider. Its vision is to enrich people’s lives through communication. The following is a brief introduction about Huawei:
- We have 5 main product lines, establishing end-to-end advantages in Telecom Network Infrastructure, Application & Software, Service and Device.
- Our products and solutions are deployed in over 100 countries and serve 45 of the world’s top 50 telecom operators, as well as one third of the world’s population.
- We generate about US $22 billion revenue in 2009.
- We have more than 43,600 employees engaged in R&D and set up more than 100 branch offices and 17 R&D centers around the world.
Delivering Task-Oriented Documentation
According to a survey, the following 3 factors are treated as the most important for our product documentation:
This reveals that customers require task-oriented documentation, i.e. the documentation should be written based on actual user scenarios and the task procedures should be described in detail and be complete.
Providing Documentation for an Increased Number of Product Variants
Catering to different markets and customers leads to an increased number of product variants. Compared with documentation that requires customers to filter out useless information, customized documentation, which is based on product configuration and customer orders, is preferred.
Producing More Content in a Shorter Period of Time
Our fast growing market share, the increased number of product variants and the shorter period for product release force us to produce more content in a shorter period of time with limited resources. In the past six quarters, the number of topics published each quarter has witnessed a continuous increase.
The following figure depicts the process of task-oriented and modular design of documentation.
Note 1: Identify information need, plan link and reuse relationships among contents
- User Model and Task Model are used as input to identify the information needs of users at the beginning of the design process, from which the Information Architect derives complete and reliable information on their needs.
- Because the information needs of users are associated with tasks, the Information Architect identifies the link among the contents by tracking the relationships among the tasks.
- The Information Architect identifies the contents that can be reused among various deliverables and product variants by analyzing common tasks, features/functions and system components.
Note 2: Distribute information need
- The Information Architect chooses the most proper media to deliver help information, for example, software UI, product packing, hardware, online help or electronic product documentation.
Note 3: Design Information Elements, Topics and Information Components
- The Information Architect builds information units with proper granularity to contain reusable contents, which then can be applied in different contexts.
- Based on the Task Model, the Information Architect divides and organizes contents into topics or information component (map).
The following are some key concepts behind this process:
Identifying the information need of users based on User & Task Analysis
As part of Huawei’s process of documentation development, the Information Architect is in charge of documentation design. The Information Architect is familiar with the product and knows how to communicate with users in simple language. However, this is insufficient to design quality user documentation. Only when the Information Architect understands the users and their tasks, can he/she grasp the information needs of users and organize the information from the users’ perspective, for example, how they will use the product.
Therefore, the User Model, the Task Model and product specifications—which are the input of the process of information design, need to be analyzed to identify the information needs of users.
The User Model states:
- Roles of the User
- Job Responsibilities or Goals of the User
- Basic Technical Skills
- Working Environment
- Preferred Way to Use Help Information
- Education Level (Reading Level)
The Task Model states:
- Tasks for the User (not the system functions)
- The Sequence of Tasks
- The Parent Task or the Subtasks
Reusing Modular Content in Multi-Granularity
Our Information Model defines three types of information units, from small scale to large scale, which are the Information Module, the Information Component and the Information Product. Based on this model, standard information units can be constructed and reused in these three types of granularities:
- Element. An Element is a part of a Topic. Typically, an Element will be embedded (reused) in more than one Topic. Element cannot be viewed from TOC or the navigation tree. The most common Elements are picture, diagram and paragraph.
- Topic. A Topic is a small independent information unit that focuses on a specific subject. Topic is the smallest section in TOC or the navigation tree. A Topic can include one or more Elements.
- Information Component. An Information Component is composed of a group of Topics or other Information Components in a certain structure. The structure of an Information Component is relatively fixed and does not vary depending on the context. Usually, an Information Component explains a product function/feature or how to perform a task, and can be reused among product variants.
- Information Product. An Information Product is a deliverable provided to end users, such as a Product Description, a Feature Activation Guide, a User Guide, and a Release Note. An Information Product is composed of a group of Topics and Information Components following a certain structure.
Using the Dedicated Design Tool
Huawei has developed a tool dedicated to this process of documentation design. This tool is based on the client/server architecture and provides the following functions:
- Allows multiple designers to collaborate online
- Manages Task Model and User Model
- Manages the common building blocks (reusable units) and topic/component templates
- Allows the Information Architect to complete the design tasks easily and flexibly
- Designs and manages the “reuse relationships” and “link relationships” among Topics
- Searches based on metadata
- Supports the DITA standard
- Provides project management reports
- Version control
- Multi-level security control
The task-oriented and modular design approach brings benefits in the following two ways:
For Customer Information Experience:
- Product documentation is structured based on users’ tasks.
- Help information is relevant, complete and just enough.
- One topic tells one story.
- Information is consistent.
For Documentation Planning, Design and Development:
- A more reliable and scientific approach to design documentation
- The Design process is defined step by step and traceable. (not a black-box anymore)
- Identify the information needs of users, more completely and more reliably.
- Provide infrastructure and rules to help the Information Architect segment and organize the content into topics or components.
- More efficient and more productive
- Provide an effective way to identify reusable content, enabling us to reuse content in maximum rate.
- The design process and the development process can work in a collaborative and parallel manner.
- Perfectly fit into the Agile process of product development.
- Integrate this design tool to the existing Information Development Platform, supported by one single CMS.
- Apply this design approach to more product lines.