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

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (7)

Semelhante a Bringing Quality and Management to End User Documentation

Semelhante a Bringing Quality and Management to End User Documentation (20)

Último

Último (20)

Bringing Quality and Management to End User Documentation

Notas do Editor