@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
Bringing Quality and Man...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
• Quality Overview
• Sha...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
3
Quality Overview
What ...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
4
Quality Overview
Why D...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
• Quality Overview
• Sha...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
6
Sharpen the Saw
Buildi...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
7
Define User Needs and ...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
8
Define Documentation R...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
9
Implement a Naming and...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
10
Work on a Project Bas...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
11
Implement a Multi-lev...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
12
Use Checklists
• Guid...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
13
Approve Documents for...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
14
Contents
• Quality Ov...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
15
Process Documentation...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
16
Why Should I Bother?
...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
17
Process Documentation...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
18
Process Documentation...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
19
Job Ticket
• Opens th...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
20
Work Instructions
• D...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
21
Checklists
• Accompan...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
22
Authorization Page
• ...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
23
Contents
• Quality Ov...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
24
Sample Process Docume...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
25
Sample – Work Instruc...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
26
Sample - Checklists
•...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
27
Contents
• Quality Ov...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
28
Conclusions
• Creatin...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
29
Contents
• Quality Ov...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
30
Filling Needs Creativ...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
31
Filling Needs Creativ...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
32
Filling Needs Creativ...
@ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz
All rights reserved.
www.englishcommunicator....
Upcoming SlideShare
Loading in …5
×

Bringing Quality and Management to End User Documentation

881 views

Published on

This presentation provides a methodology for efficiently managing the document creation and review process.

Published in: Business, Technology
  • Be the first to comment

Bringing Quality and Management to End User Documentation

  1. 1. @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
  2. 2. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. • Quality Overview • Sharpen the Saw • Process Documentation • Sample Process Documentation Set • Conclusions • Bonus Material – Filling Needs Creatively 2 Contents
  3. 3. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 4. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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
  5. 5. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. • Quality Overview • Sharpen the Saw • Process Documentation • Sample Process Documentation Set • Conclusions • Bonus Material – Filling Needs Creatively 5 Contents
  6. 6. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 7. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 8. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 9. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 10. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 11. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 12. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 13. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 14. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 14 Contents • Quality Overview • Sharpen the Saw • Process Documentation • Sample Process Documentation Set • Conclusions • Bonus Material – Filling Needs Creatively
  15. 15. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 16. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 17. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 17 Process Documentation 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. 18. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 18 Process Documentation 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. 19. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 20. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 21. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 22. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 23. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 23 Contents • Quality Overview • Sharpen the Saw • Process Documentation • Sample Process Documentation Set • Conclusions • Bonus Material – Filling Needs Creatively
  24. 24. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 25. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 26. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 27. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 27 Contents • Quality Overview • Sharpen the Saw • Process Documentation • Sample Process Documentation Set • Conclusions • Bonus Material – Filling Needs Creatively
  28. 28. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 29. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 29 Contents • Quality Overview • Sharpen the Saw • Using Process Documentation • Sample Process Documentation Set • Conclusions • Bonus Material – Filling Needs Creatively
  30. 30. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 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. 31. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 31 Filling Needs Creatively 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. 32. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. 32 Filling Needs Creatively 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
  33. 33. @ricktep | richard12@012.net.il | englishcommunicator.com© 2011 Rick Teplitz All rights reserved. www.englishcommunicator.com englishcommunicator@gmail.com

×