Pittsburgh PA 15213 -3890 Concepts for Writing Effective

Agenda Background/Typical Problems Information Mapping™ principles Exercise in Recognizing Different Process Guidance Information Types

Typical User Problems in Process Guidance Information Too 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 Understanding “Types” of Process Assets Objective: Understand different ways to structure process asset information Copyright 2004, Carnegie Mellon University. All rights reserved.

Information Types Related to Guidance Documentation Principles Procedures Processes From Information Mapping™ courses Structures on designing information -- a techniqu based on 30+ years of research on Concepts learning and information representatio Facts Classification

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 Concepts Chunking: • 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 Documents Don’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 Documents Use 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 Policy 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 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