Bringing Quality and Management to End User Documentation

@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
Bringing Quality and Management
to End-user Documentation
Prepared and Presented by:
Rick Teplitz

• Quality Overview
• Sharpen the Saw
• Process Documentation
• Sample Process Documentation Set
• Conclusions
• Bonus Material – Filling Needs Creatively
2
Contents

3
Quality Overview
What is Quality?
• ISO: The totality of features and characteristics of a product or
service that bears on its ability to satisfy stated or implied needs
• IEEE 1: The degree to which a system, component, or process
meets specified requirements
• IEEE 2: The degree to which a system, component, or process
meets customer or user needs or expectations
ISO: International Organization for Standardization
IEEE: Institute of Electrical and Electronics Engineers

4
Quality Overview
Why Do We Need Quality in Documentation
• To increase the usefulness of our product
• To increase the value of our product
• To increase our competitive edge
• To project professionalism
• To provide competitors with reading material for the plane

• Sharpen the Saw
• Conclusions
5
Contents

6
Sharpen the Saw
Building a More Efficient Environment
• Defining user needs and expectations
• Defining documentation requirements
• Implementing a naming and tracking system
• Working on a project basis
• Implementing a multi-level review process
• Using checklists
• Approving documents for use

7
Define User Needs and Expectations
User: anybody who uses our documentation for reference
• Reviewing existing documentation. Identifying its strengths and
weaknesses
• Discussing needs and expectations with relevant staff (product
managers, sales engineers, customer support)
• Conducting surveys with customers regarding how they use
documentation if possible (examples)
• Understanding what information is most important
• Developing documentation around use models (printed
documentation, OLH search)

8
Define Documentation Requirements
• Reviewing available background material (MRDs, FRSs, etc.)
• Interviewing SMEs and participating in product development if
possible
• Identifying new modules and features
• Listing major features and procedures involved with
configuration and use
• Writing up summary of requirements (Job Ticket)
• Having all parties review and approve requirements
• Verifying this information is in the final product

9
Implement a Naming and Tracking System
• Needed to provide proper support to customers
• Each document needs to be traceable
• Each document needs to display application version and
document version in a single location
• Final documents need to be archived
• File names and references are key to tracking

10
Work on a Project Basis
• Defined from the start
• Have a start, middle and end
• Requirements approved by all parties, before beginning
• Reviewed at various stages
• Result in Approval (an “Authorized” version)

11
Implement a Multi-level Review Process
• Review by multiple parties is key to quality
• Define reviewers involved in process
• Define levels of review (draft 1, draft 2, v1.0).
• Use checklists to accompany the review process
• Make process traceable from start to finish
• Process ends in Approval

12
Use Checklists
• Guide the writing and updating of documents
• Accompany the various stages of writing and review
• Guarantee that necessary items have been included and
reviewed
• Assist in traceability
• Work as “handshake” between the parties

13
Approve Documents for Use
• Guarantees that all responsible parties have reviewed the
document
• Defines the end of the review process
• Provided by having multiple parties sign off on an
Authorization page
• Represents an “authorized” version, ready for distribution to
customers
• May be required to be compliant with standards

14
Contents
• Sharpen the Saw
• Conclusions

15
Process Documentation
Why do we Need It?
• Guarantee a smooth workflow
• Help adhere to deadlines
• Guarantee all information has been included in documents,
from the start
• Avoid last minute surprises
• Provide transparency and ease report-ability
• Maintain standards such as ISO
• Train new employees

16
Why Should I Bother?
Common Complaints
• Its just covering your butt! Well, kind of…
– Not trying to assign blame, trying to discover problems and understand
how to fix them
– Improve the process by making it smoother
– This time, there were problems, next time things will go more smoothly
• The last thing we need is more bureaucracy
– Checklists need to be short and to the point. They should assist, not
encumber

17
Identify Main Tasks
• Identify main tasks and understand their workflow, such as:
– Writing a new manual or adding features to existing manuals
– Creating online help
– Conducting a multi-party review
– Releasing a product
• Identify other procedures or support mechanisms that should
be defined, such as:
– File naming
– Documents part of a release

18
Build Documentation Around Main Tasks
• Job Ticket: Initiates a project, lists all requirements BEFORE a
project is started
• Work Instructions: Provides overview of the main processes
(update manual with new feature)
• Checklists: Guides the update and review process, list common
elements that need to be reviewed
• Authorization Page: Closes a project. Signed by minimum of
three parties
Customize to your Needs

19
Job Ticket
• Opens the document writing and updating processes
• Lists the various details involved in the project
– Version information
– Level of update requested (e.g., minor, major, complete overhaul)
– Documents to be updated
– New features that need to be added
– Features included with specific version
– Deadlines and time to completion estimates
• Is completed, then reviewed by all parties before beginning

20
Work Instructions
• Define main stages of a process (draft, review by PM, review by
QA, making edits)
• Provide detailed description of the process from start to finish
• Review roles and responsibilities of all participants
• Contain a diagram illustrating the process
• Can optionally list specific tasks for participants

21
Checklists
• Accompany and guide a process (e.g., review)
• List basic information including date, filename, and other
relevant information
• Provide short instructions on how to use checklist
• Provide a short, concise list of items that can quickly be
completed, per participant
• Provide space for the addition of comments per item
• Should be completed during review, not after

22
Authorization Page
• Completes the document cycle
• Should be signed and dated by a minimum of three parties, for
example, Manager, QA and TW.
• Is filed in a binder together with the approved version
• Approves document for release

23
Contents
• Sharpen the Saw
• Conclusions

24
Sample Process Documentation Set
• Job Ticket
– PM-CL-004-Job-Ticket
• Work Instructions
– PM-WI-001-Document-Review
– PM-WI-002-Document-Release
– PM-WI-003-Product-Management-FileSystem
– PM-WI-004-File-Naming-Conventions
– PM-WI-005-User-Manual-Upgrade
– PM-WI-006-Docs-Provided-with-Release
– PM-WI-007-Applications Provided with-Standard-Release
• Checklists
– PM-CL-001-Document-Review-Checklist
– PM-CL-002-Document-Release-Checklist
– PM-CL-003-OLH-Review-Checklist
• Authorization Page
– PM-TP-007-Authorization-Page

25
Sample – Work Instructions
• User Manual Upgrade: defines the overall process of upgrading
a user manual
• Document Review: defines the review process
• Document Release: defines the release process
• File Naming Conventions: defines document and reference
naming conventions
• Docs provided with Standard Release: lists standard
documents provided with release

26
Sample - Checklists
• Document Review Checklist: guides the reviewing of a specific
document
• Document Release Checklist verifies:
– All required documents have been updated and included with release
– New docs have been uploaded to Intranet
– Final versions have been archived
• OLH Review Checklist: guides the reviewing of On-line Help

27
Contents
• Sharpen the Saw
• Conclusions

28
Conclusions
• Creating quality involves understanding customer needs,
developing clear processes, pre-determined requirements, review
and approval
• A project should have a start, middle and end
– Start: Requirements should be approved by all parties
– Middle: Project phases accompanied by checklists
– End: Final approval should be provided to a project
• Bringing quality and management involve:
– Identify and define the main processes conducted to complete tasks
– Document processes so that everybody understands how they work
– Guide processes using checklists that assist in conducting major tasks
– Update and improve these processes to match a changing environment

29
Contents
• Sharpen the Saw
• Using Process Documentation
• Conclusions

30
Filling Needs Creatively
A Case Study
• Our product tested the WAN under varying conditions
• Came with pre-configured sample files that customers could use
• Each new sample file required detailed instructions
• Feature requirements were originally written by Israeli SME
located in the US
• Problems:
– Difficult to acquire information, time difference
– Test file did not meet original expectations
– Not properly developed (because it was not clearly defined)
– The end product was not properly tested, and was difficult to document

31
The Solution: Test File Specifications
• Single form filled out by SME
• Detailed all aspects of required test file including general use
case, required components, configuration parameters, test steps
and basic architecture diagram
• Accompanied test file at every stage of feature development
lifecycle
• Helped in maintaining expectations with everybody involved
• Resulted in a final product that was faithful to original objective
and providing reliable support material

32
Guidelines for All Stages of Feature Lifecycle
• Sales: Completes test specifications to
assist in defining the test file
• Product Management: Draws up feature
specifications based on this information
• Development: Use specifications to
develop working test file
• TW: Uses specifications to prepare
documentation
• QA: Follows steps detailed in test
specifications as part of testing, confirm
smooth operation of test file
• Sales: Uses document based on
specifications as tool to describe product
to potential customers
• Customer: Uses document based on
specifications to understand test file
• Support: Uses document based on
specifications to assist in supporting
clients

www.englishcommunicator.com
englishcommunicator@gmail.com

Bringing Quality and Management to End User Documentation

Recommended

Recommended

More Related Content

What's hot

What's hot (7)

Similar to Bringing Quality and Management to End User Documentation

Similar to Bringing Quality and Management to End User Documentation (20)

Recently uploaded

Recently uploaded (20)

Bringing Quality and Management to End User Documentation

Editor's Notes