Writing Software Documentation, Chapter 5 – Nelson & Haupt

Barker’s Chapter 5 informs us on the importance of the research phase of analyzing documentation users. Analyzing user research should be done with interviews, questionnaires, and surveys, either choosing to do one of the research types or all three. When analyzing the users it is best to focus on the eight areas of; tasks and activities the user will perform, user’s informational needs, users work motivations, level of the user’s computer experience, knowledge of the program’s subject matter, community, learning preference, and the user’s usage patterns. Try to immerse yourself into the workplace world of your users, list as many types or groups of the users as you can. Which users would most probably use the program and which users can be interview most easily.

Keep in mind the importance of sensitivity to the culture the users comes from and their nations or workplaces. When analyzing a user it is important to know that you may need to get authorization to interview people in the workplace. Pay particulate attention to information related tasks like communicating, storing, and sharing.

Barker points out to analyze the users before and after tasks by noticing small facts about the users, their attitudes and habits. Look for items such as notes stuck to bulletin boards, diaries of skills, or third-party computer manuals that the users employ in their daily use of existing technology.


In some instances a mock-up of the user or a model may need to used to perform the research. Barker suggests the use of library occupational guides, placement services that college or university use, or even job descriptions found in publications put out by companies.

Remember that deadlines and timeliness of reports often are what makes documentation useable or not. To help out in the research the use of a flow diagram may help to better clarify how the users' tasks are being accomplished.

When planning to do research Barkers suggests following some general steps.

1. Research into the user’s job and the programs.


2. Review the software..


3. Establish the scope, how many, with whom, etc..


4. Make a list of interview questions..


5. Get permission..


6. Set a schedule, date, times, and places..


7. Follow up, thanks you letters, reviews, and testing..

Techniques for Analyzing

1. Shadowing, observe the user by spending time at the workplace watching the users perform their jobs and tasks in addition to interviews and questionnaires.


2. Getting involved, don’t let the user know what you want to happen ahead or time because you may run the risk of chancing what happens naturally.

Barker mentions the use of cultivating a relationship with the users. What Barker does not mention is that if not done correctly then having a relationship may alter the research being done.

Chapter 5 describes the process of performing a user analysis as the initial stage in creating software documentation.

The user analysis is divided into eight categories:

1. Tasks and activities the user will perform


2. User’s informational needs


3. User’s work motivations


4. Level of the user’s computer experience


5. User’s knowledge of the program’s subject matter


6. User community


7. User’s learning preference


8. User’s usage pattern

The procedure for conducting a user analysis also consists of eight steps:

1. Choose users carefully


2. Anticipate transfer of learning: study users before and after using a program.


3. Research professional behaviors


4. Write use cases


5. Plan interviews carefully


6. Involve users in all phases of the project


7. Identify document goals


8. Tie the user analysis to document features

Each of these steps is described in detail in Chapter 5. It should be noted that the process described in this chapter is applicable only to large-scale documentation projects. The level of detail required has a direct relationship to the complexity level of the software application. Small projects will still require the technical communicator to perform a user analysis but it will be scaled back in scope and detail.

On large projects the technical writer is part of a dedicated writing team. This team normally consists of a manager, lead writer, writer, editor, graphics designer and test. The writing team works with the development team. The development team is usually composed of a project manager, software developers, market/systems analysts, technical specialists/programmers, and a documentation specialist. Additional information on these teams is found in Chapter 6.

It is common for the writing team to simultaneously develop documentation for multiple publishing formats. These can include hardcopy, PDF, online (HTML and XML), help systems, and localized (translated) versions of the documentation.

The user analysis phase of a project can last for months. During this time both the development and writing teams have extensive interaction with the user community. In the case of single source documentation projects the user analysis phase can become a development project all of its own. This is because actual document analysis must be performed to accurately describe the logical structure of different classes of legacy user documentation. Once the structures have been defined the development and/or writing teams will code those structures into XML/SGML schemas and/or Document Type Definitions (DTDs). Of particular interest is the fact that if Framemaker will be used by the user community then an additional step is necessary. The DTDs will need to be translated into Framemaker Element Definition Documents (EDDs). The EDDs merge logical structures with typographical markup. Thus, a user creating documentation based upon an EDD will be able to use Framemaker to compose fully marked-up text and then save that text in to a content management system and eventual use in an online documentation publication.

Something the text does not cover but is becoming increasingly common in user analysis is the creation of taxonomies. Taxonomies are systems of subject classification. These are important to online technical communicators because of the emergence of the Darwin Information Typing Architecture (DITA). DITA provides a framework for storing text elements (for inclusion in online compound documentation) based on subject headings. The key is that DITA does not define the classification of the logical structure of your subjects (taxonomies) for you. That is left for the development/writing teams to accomplish. Once taxonomies are defined they can be hard-coded into the XML data repository for a single sourcing content management system. At this point the authors using the system will be able to construct and manage online content based on custom subject tree structures (taxonomies) for their organization.