Pittsburgh, PA 15213-3890

Copyright 2004, Carnegie Mellon University. All rights reserved.

Concepts for Writing Effective Process Guidance

Suzanne Garcia

Agenda

Background/Typical Problems

Information Mapping™ principles

Exercise in Recognizing Different Process Guidance Information Types

Typical User Problems in Process Guidance InformationToo many different types of guidance all in one document

Inconsistency in the types/level of guidance provided

Difficulty finding the information you need

Lack of “shared mental model” on how information should be organized

Remember the purpose of Process Documentation

Capture intentions for future reference• in case details/agreements are forgotten

Capture expectations for what will happen when activities are performed• shortens training time

Capture expectations to support developing time estimates for activities

Capture expectations for communication documents• so people know what to expect from one another• so actual resuts can be compared to expected results

Adapted from K. Caputo, CMM Implementation Guide: Choreographing SW Process Improvement, 1998

Different Types of Guidance

“Information types” provides a way of looking at different types of guidance information and segregating it according to the tasks it supports

Pittsburgh, PA 15213-3890

Copyright 2004, Carnegie Mellon University. All rights reserved.

Understanding “Types” of Process Assets

Objective: Understand different ways to structure process asset information

Information Types Related to Guidance Documentation

PrinciplesProceduresProcessesStructuresConceptsFactsClassification

From Information Mapping™ courseson designing information -- a techniquebased on 30+ years of research on learning and information representation

Principle

Typical contents:

• Policy, rules, constraints, guidelines

Guidance:

• use strong, active language

• use a label that clearly indicates the use of the information in the document/section

• often includes “why” information to motivate acceptance of the principles

Process

Typical contents:• description of “what needs to happen”• focused on characterizing the vision for getting to a goal• characterizes relationships and controls/measures• roles help people “find themselves” in the process

Guidance:• use third person language, active voice• make cause/effect relationships clear• “flow” should move forward over time• stay away from “how to”--> not too detailed• diagrams provide good “overview”• tables useful for grouping information related to the

process

Procedure

Typical contents:• “how to” complete steps in a task or process element• action-focused• defines different decision points

Guidance:• begin each step with an “action” verb• make sure steps are distinct• make decision points/resolution clear• tables and flowcharts are typical “forms”• “lists” of steps less effective expression, but most

commonly seen!

Concept

Typical contents:

• definitions

• examples/non-examples

• critical attributes of a subject

Guidance:

• illustrate the critical attributes in a definition with an example and, where feasible, a “non-example”

• identify relationship of concept to a larger subject

Fact

Typical contents:

• facts, data, relevant to understanding the concepts, constructs, and structure of the subject

Guidance:

• clearly label the information as to its relationship to the relevant aspects of the subject that are covered in other areas of the document

Structure

Typical contents:

• elements of a subject and their relationships

• architectural information

• reference information

Guidance:

• diagrams are a good way to communicate high level and detailed relationships

• “parts/function” tables provide links between definitional and structural information

Classification

Typical contents:

• lists, hierarchies

Guidance:

• introduce lists

• place most important sorting factor on the left

• use “parallel language” -- same type of language for each level in the hierarchy

Other Important IM ConceptsChunking:

• visually distinguish related “chunks” of material so readers can find what they’re interested in

Relevance:

• keep things together that are needed to meet the purpose of the document/section

• use the right representation for the right information type

Hierarchy:

• break the information down into “chunks” in a way readers can move from general to specifics

Labeling:

• label the information in a way that tells the user what to expect

Important IM Concepts-2

A defined writing PROCESS:

• analyze audience and their use of the information

• define the types of information needed to meet the audience’s needs

• define the organization of the information to optimize user navigation based on their defined needs

• plan the elicitation of the information for the document from relevant subject matter experts

• execute the plan

• test the document design with pilots

• complete the document/publish

Suggestions: Policy DocumentsDon’t forget Policy documents are not just documents, they’re also a way to group things together• Primarily composed of Principle types of information

Policies are statements of commitment to a way of conducting business…don’t need very many of them, per se• DON’T write a policy for every Process Area you’re

implementing!- Look at your existing policies structure and see where

principles related to the PAs (often found in the Purpose/Introductor Notes section) can be incorporated

Suggestions: Process DocumentsUse diagrams to help focus your readers

Highlight interactions among multiple roles

A simple set of things to know about elements of a process:

• Who does it? (role)

• What do they do? (tasks)

• What is the outcome when they do it? (deliverables)

Lots of other questions can be asked/answered, but if you can’t answer these, you can’t see basic relationships that will be important to understanding the process and how to improve it

Suggestions: Procedure/ Guidelines Documents

Stay “single role-focused” for Procedures

Guidelines help fill in the blanks wherever information is needed to support • processes, procedures, or templates

Procedures focus on “how”—typically focused on the person new to performing the task vs an expert• But procedures usually assume the individual has

competence in the general area being addressed – procedures are NOT meant to be a substitute for training!

Use active voice, active verbs to emphasize procedural content

Mapping These Process Guidance Types to a Typical ISO 9001 Structure

Work Instructions Procedures/Guidelines

Operating Manual mix of Processes and Procedures/Guidelines

Common Operating Processes mostly Processes, sometimes high level Procedures also appear

PolicyPolicy

The above are all “auditable” from an ISO 9001 point of view; you may also want to consider adding guidelines that are not auditable: “informative” aspect of your ISO documentation. These would map typically to Procedures/Guidelines

Summary

Information types provide clear criteria for distinguishing different types of process guidance and suggestions for how to represent different types of process guidance.

ISO 9001 documentation doesn’t typically map one to one to process guidance information types, but can be organized to reflect this approach

• We’re not suggesting you reorganize everything this way – we are suggesting you use your current organization, but clearly identify the different information types you are using to help guide readers on what to expect

EXERCISE: Recognizing Different Information Types

Read the handout and mark phrases/sentences that indicate

• Principles (Policy)• Procedures• Processes• Structures• Concepts• Facts• Classification

Think about if/how you would reorganize this document to make its appropriate use easier/clearer