Geetha Haridas, Qualcomm
January 15, 2023
User documentation plays a critical role in helping users to understand how to use software products. Although the belief that ‘nobody reads documents’ still exists, research studies by Schriver (1997) suggest that users, regardless of their age or gender, read documentation to understand and use products and technology. However, documentation can be successful only if it meets the requirements of users (Schriver 1997).
The demand for quality documentation has given rise to concepts such as information design that are concerned with creating usable information for users. However, information design is a vast field that has been defined in various ways. Information design sometimes involves enhancing the appearance and readability of documentation (Burnett 2001). In some other contexts, information design is a problem-solving activity that authors carry out to create usable documentation (Carliner 2001). Multiple and contradictory views about information design often make it difficult to apply this concept in a practical context.
What is information design, and how does it add value to a document? This article explores the challenges in understanding information design and offers a definition for information design in the context of software product documentation. The article describes a three-stage process for applying information design to create product documentation that satisfies specific requirements of users.
Defining information design
In defining information design, theorists usually highlight the visual and communicative aspects of documents.
Burnett (2001) suggests that “Information design is a field concerned with ways in which you can organize and present information to affect reader’s comprehension” (Burnett 2001, p.247). This definition highlights the use of textual, spatial, and graphic elements for designing print documents or web pages
Sless (1994) notes that information design should be applied to help readers with accomplishing specific goals and argues that “Information design is about managing the relationship between people and information so that information is accessible and usable by people”.
Information design can therefore be defined and practiced differently in different contexts. To understand how to apply information design to software product documentation, it is essential to understand how users use product documentation.
Users of a software product require functional or how-to information to perform tasks related to installing, administering, using, or troubleshooting the product. Inaccurate information, no matter how easy-to-read, or visually elegant, fails to satisfy the requirements of these users. Authors must therefore design product documentation to achieve practical purposes, so that users can locate and use information effectively (Schriver 1997). Information design, in this context, is a problem-solving activity that helps users to achieve specific objectives. Even so, presentation and use of visuals are a part of this activity, as they make information more comprehensive and readable.
In defining objectives for information design, Carliner (2001) has prescribed a model-based approach that addresses information design at three levels:
- Physical, the ability to find information.
- Cognitive (intellectual), the ability to understand information.
- Affective (emotional), the ability to feel comfortable with the presentation of information.
- This model or framework specifies the levels of information design that a document should achieve. This model also relates to the following definition offered by Redish (2000), which takes a practical approach and translates these information design levels into specific user requirements:
“Information design is what we do to develop a document (or communication) that works for its users. Working for its users means that the people who must or want to use the information can:
- Find what they need.
- Understand what they find.
- Use what they understand appropriately.”
- This definition suggests that “most users of functional information are using the information to reach a personal goal – to answer a task or to complete a task” (Redish 2000). It focuses on helping users to locate, understand, and use information for achieving their goals, which are the primary objectives that product documentation should achieve.
Building on this definition, information design in the context of product documentation can be defined as the process of designing, developing, and delivering usable information to users so they can use the information to perform their tasks effectively.
The design and delivery stages focus on helping users ‘to find what they need’. These stages involve understanding user requirements, structuring and delivering information so that users can locate the required information.
The development stage is aimed at helping users to ‘find, understand, and use information’. This stage involves creating information that helps users to perform their tasks.
Usable information is the correct level of accurate information, neither too much nor too little, tailored to meet the knowledge level of users.
Information design is a process that flows through the stages of the documentation lifecycle
Information design as a process
- A common misconception about information design is that it can be carried out as a set of activities on a finished document to make it more usable (Schriver 1997). In contrast, information design is a process that flows through the stages of the documentation lifecycle. Carliner (2001), Sless (1994), and Redish (2000) have used process models to demonstrate how information design can be practiced within the documentation lifecycle.
Design, development, and delivery are the three key stages around which a documentation lifecycle is built, although intermediate stages can be added. For example, drafting, testing, and writing content are a part of the development process. To design documentation that satisfies user requirements, authors must carry out information design as a process within this lifecycle and achieve specific objectives.
Stage 1: Design
- In the design stage, information design involves defining the purpose of the documentation and how the purpose must be achieved.
Schriver (1997) notes that information design involves recognizing situations where documents might be beneficial and discovering how they can be employed for achieving specific goals. Hence, to define the purpose of the documentation, authors must understand user requirements and the product functionality.
Determining user requirements involves:
- Understanding the user roles involved in setting up and using the product.
- Identifying the tasks each type of user is likely to perform.
- Understanding the level of knowledge required to perform each task.
- By bringing users into the process, authors can create information tailored to the requirements of users (Schriver 1997).
Understanding a product involves:
- Understanding the purpose of the product.
- Identifying the workflows in a product.
By understanding the workflows and mapping them with the user requirements, authors can identify the tasks that they must document and the types of guides they must create to support the product.
The objective of this stage is to create an outline or a structure to define how the documentation must be written. Carliner (2001) has listed ‘creation of the outline’ as a separate step in the documentation process, describing it as a blueprint that determines how a guide should be written. Burnett (2001) describes an outline as a tool that can highlight the gaps, inconsistencies and flaws in the flow of information, and notes that authors can arrange and examine their ideas by creating outlines.
The outline developed in the design stage predominantly determines whether or not users can ‘find what they need’.
Stage 2: Development
- In the development stage, information design involves creating quality content. Authors must ensure that the content they write matches the experience level of users (Hargis et al. 2004). Authors must find a balance between providing too much and too little information. Creating quality documentation also involves adding value to and removing redundancy from information.
Adding value to documentation involves providing relevant context about a specific task, without questioning the intelligence of a user. It involves ensuring the clarity and completeness of information by:
- Using a task-based approach, writing in terms of how a user actually does a task. “Authors rarely help users when they tell users how a product works or is structured internally” (Hargis et al. 2004).
- Writing in a clear readable style. Using adequate white space, tables, and lists to structure and present information so that users can scan the information quickly.
- Providing examples that are relevant to the users’ environment or culture (Carliner 2001).
- Providing answers to questions such as ‘why’, ‘what’, and ‘how’ that users might have about the product.
- Ensuring the accuracy of information, either by reviewing or testing the documentation.
- Removing redundancy involves eliminating repeated information, intuitive screenshots, and instructions that do not add value. For example, experienced users might not require screenshots showing every field of a user interface.
The quality, accuracy, and presentation of the information written in the development stage determine whether or not users can ‘find what they need’, ‘understand what they find’ and ‘use what they understand’.
Stage 3: Delivery
In the delivery stage, information design involves choosing an appropriate medium of delivery depending on how users might want to access the information.
Product documentation, however well-planned and well-written, is not useful if users cannot access it when required. For example, if installation information is provided in an Online Help that can be accessed only post-installation, such information is of little use to the user.
Authors must therefore carefully decide the medium of delivery so that users can ‘find what they need’ and when required.
How information design satisfies user requirements
Figure 1 shows how information design ties in with the documentation life cycle and how the activities carried out at each stage satisfy specific user requirements.
Product documentation, however well-planned and well-written, is not useful if users cannot access it
The development stage emerges as the key stage, for it plays an important role in satisfying all the user requirements. Perhaps this is why managers, and sometimes authors, underestimate the importance of documentation planning and focus on the development process, especially where there are time or budget constraints.
However, authors must not ignore the importance of the design and delivery stages. The design stage serves as the foundation for development, whereas information is communicated to users through the delivery medium. These stages clearly strengthen the possibility of enabling users to ‘find what they need’. Users cannot understand and use information if they cannot find it. Therefore, even if authors cannot follow the complete process when creating product documentation, it is beneficial to provide some thought to each stage of information design.
Burnett R.E. (2001) Technical Communication, Harcourt Publishers, 5th edition.
Carliner S. (2001) Article: Physical, Cognitive, and Affective: A three-part framework for information design.
Hargis, G., Carey, M., Hernandez, A.K., Hughes, P., Longo, D., Rouiller, S., and Wilde, E. (2004). Developing Quality Technical Information: A Handbook for Authors and Editors, 2nd ed., Prentice Hall.
Redish J.C. (2000) What is information design?, Technical Communication, May 2000, vol.47.
Schriver K.A. (1997) Dynamics in Document Design: Creating Texts for Readers, Wiley.
Sless D. (1994) Designing Information for People, Communication Research Institute of Australia, 2nd edition.
Geetha Haridas has a Master’s degree in Technical Communication and over 20 years of experience in designing and developing software product documentation. She currently works as a Senior Staff Technical Writer at Qualcomm, Cambridge.
E: [email protected]
This article originally appeared in the Communicator journal published by the Institute of Scientific and Technical Communicators (ISTC), UK.