1. Pittsburgh, PA 15213-3890 Copyright 2004, Carnegie Mellon University. All rights reserved. Concepts for Writing Effective Process Guidance Suzanne Garcia

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

3. 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

4. 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

5. 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

6. 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

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

8. 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

9. 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

10. 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!

11. 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

12. 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

13. 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

14. 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

15. 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

16. 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

17. 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

18. 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

19. 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

20. 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  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

21. 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

22. 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