Performance-based DocumentationMalcolm Graham ESN 393-2231

S954, Lab 3, CAR (043/33/H02)

This presentation will...

• Present a performance-based development model that relates information to acceptable user performance in acquiring specific skills and knowledge

• Describe how existing techniques from the documentation, training, IP-based product management, and the information technology fields are incorporated in the model

• Show how Nortel Networks information products can be developed to provide users with a truly Compelling Web Experience

Document design

Before selecting and organizing document content, it is important to:

To meet these requirements, this presentation:

• define content purposes• identify how each purpose will be achieved• know how purpose success will be verified

• defines the main purpose of product documentation• explores adult learning and behavioral objectives• describes a generic Information Category Model• presents two examples that use the model

Let me tell you a story...

• Sea horse seeking fame and fortune...

>Where do I want to go? >How do I get there?>Did I arrive?

• Relevance to selecting and designing information products?

Purposes information category

• Overall purpose? Communicate skills and knowledge to users in such a way that they will be able to demonstrate acquisition of skills and knowledge required to use product efficiently and effectively

• Six sub-purposes, to buy, plan, train, install, operate, maintain

• This category enables information to be associated with the intended use of the information

Adults learning...

Acquisition of skills and knowledge requires that we define the required performance, conditions, and criterion of acceptable performance. This is facilitated by defining behavioral objectives for all information modules.

Many adults...

• resist learning anything new• avoid reading• when using new systems, often guess how it works• conditioned to have a production bias, throughput paramount• rely on existing skills and knowledge

Behavioral objectives...Information products need to...

Behavioral objectives need to...

• minimize reading and searching

• provide immediate feedback on task completion

• present information that links to existing skills and knowledge

• define small tasks for quick assimulation and feedback

• be clearly presented and used as criteria for success

• be part of hierarchy of expected behaviors

• use familiar language

• be phrased so that they can be used for usability testing

Examples of objectives...Document type Purpose Behavioral objective

(users will be able to do the following)

Product introduction Buy, Plan, Install,Train, Operate,Maintain

State the purpose of the product List the main product components

Sales & Order Guide Buy Describe main product features & value Complete an order form

Planning Guide Plan List the main product components Draw a product relationship diagram Write a brief product description Draw a diagram of the product Locate & list available information products Complete a sample planning exercise

Installation Guide Install Identify main hardware & software Locate & list available information products List main installation tasks Start the product Verify correct installation

User Guide Train, Operate,Maintain

Locate & list available information products Monitor product-related activity Capture & organize data logs Identify common alarms & failures Locate troubleshooting procedures Locate & replace faulty components

Information categories (1 of 2)

Good design is of little use if you can't find what you want when you need it. All information must map to user tasks and be provided when needed. This can be achieved by categorizing all objectives. I have identified 4 main information categories:

• USERS (associates information with specific types of user)

• PURPOSES (associates information with its intended use)

• TASKS (associates information with user tasks)

• PRIMITIVES (associates information with information type)

Information categories (2 of 2)

• USERS is the parent of PURPOSES; PURPOSES is the parent of TASKS; and TASKS is the parent of PRIMITIVES

• The USERS category could serve as the entry level for the other categories (via the WEB or the product API)

• The USERS, PURPOSES, TASKS, and PRIMITIVES categories are used to tag all modules (statically or dynamically)

• Hierarchical and associative relationships between each category and all modules is defined by means of tags (for example, XML tags)

• All information is modular; information categories define how the modules are accessed

Users information category

• Depends on the product, but generic ones could be defined; for example:

• This category enables information to be associated with the information needs of users

> Buyer> Planner > Trainer> Installer> Operator> Maintainer

Tasks information category• Depends on the product, but generic ones could be defined;

for example:

• This category enables information to be associated with tasks that have to be performed by users

> Operate > Configure > Describe > Monitor > Test> Order > Plan > Bill > Replace > Group> Sort > Install

Primitives information category

> Messages > Alarms > Services> Hardware

• This category enables information to be associated with the type of product information needed by users

• Depends on the product, but generic ones could be defined; for example:

Information category model

The following three slides present the Information Category Model and two examples that illustrate its use

1.0 Users

1.1 Buyer

1.2 Planner

1.3 Trainer

1.4 Installer

1.5 Operator

1.6 Maintainer

1.7 Developer

2.0 Purposes

3.0 Tasks

2.1 Buy

2.2 Plan

2.3 Train

2.4 Install

2.5 Operate

2.6 Maintain

3.1 Operate

3.2 Configure

3.3 Describe

3.4 Monitor

3.5 Test

3.6 Order

3.7 Plan

3.8 Bill

3.9 Replace

3.10 Group

3.11 Sort

3.12 Install

4.1 Messages

4.2 Alarms

4.3 Services

4.0 Primitives

4.4 Hardware

Information Category Model

1.0 Users 1.5Operator:OperateMonitorConfigure

1.6Maintainer:MaintainTestReplaceGroupSort

2.0 Purposes

3.0 Tasks

2.5 Operate 2.6 Maintain

3.2 Configure 3.4 Monitor 3.5 Test

4.1 Messages 4.2 Alarms 4.3 Services4.0 Primitives

API or Web

3.9 Replace 3.10 Group 3.11 Sort

Information Modules

Interpret_Alarm1. Click button on network mapGet Alarm Monitor Window2. Click on button for Component3. Click on AcknowledgeGet description and suggested corrective actions4. Interpret suggestions5. Click on Open or Test Resource6. Identify probable cause

Card_Replace

Card_Configure

Card_Test

Alarm_Clear

Event: Operator is configuring a network path when an alarm is indicated on a component

4.4 Hardware

Example 1

1.0 Users 1.5Operator:OperateMonitorConfigure

1.6Maintainer:MaintainTestReplaceGroupSort

2.0 Purposes

3.0 Tasks

2.5 Operate 2.6 Maintain

3.2 Configure 3.4 Monitor 3.5 Test

4.1 Messages 4.2 Alarms4.4 Hardware4.0 Primitives

API or Web

3.9 Replace 3.10 Group 3.11 Sort

4.3 Services

Information Modules

Interpret_Alarm1. Click button on network mapGet Alarm Monitor Window2. Click on button for component3. Click on AcknowledgeGet description and suggested corrective actions4. Interpret suggestions5. Click on Open or Test Resource6. Identify probable cause

Card_Replace Card_ConfigureCard_Test

Alarm_Clear

Event: Maintainer advised that the card in shelf 2, slot 4 is dead

Example 2

Model implementation...

The model can be implemented in 3 stages:

• Stage A: Define behavioral objectives for each document module and organize information accordingly; identify SNMP MIB data

• Stage B: Categorize all objectives using generic information categories and assign all information modules to one or more categories; tag all information with the assigned categories using XML and associate with related SNMP MIB data

• Stage C: Perform usability testing using the objectives defined in Stage A as the evaluation criteria. Use formative usability on each module during their development and summative usability on the completed document

Conclusions

• Using a performance-based model for developing product documentation involves considering user needs from conception to completion. The resulting documentation is more likely to meet the actual information needs of users

• The model combines existing, tried and tested, techniques from the documentation (structure), training (objectives), and IP-based product management (SNMP MIB) fields; it can also accommodate the latest information technology (XML)

• The model supports multi-authorship since each module can be tested separately. The model also supports Web-based information development and the provision of specific information on a just-as-needed basis to provide users with a truly Compelling Web Experience