dojo master -doc plans
Post on 07-Jul-2015
170 Views
Preview:
DESCRIPTION
TRANSCRIPT
6/9/2014TC Dojo Open Session
Creating a Documentation Plan
John Hedtke, Double Tall ConsultingFellow, Society for Technical Communication
6/9/2014TC Dojo Open Session 1
Speaker BackgroundJohn Hedtke has worked in high tech for
over 30 years and has written documentation and books for many leading software products. John owns and operates Double Tall Consulting, a company that provides writing, consulting, and training services to private and government clients in all fields. He also runs a blog for people who want to become authors at http://tradebookauthor.com.
When not otherwise occupied, John plays the banjo, writes magazine articles, and writes slogans for a button company. John is a Fellow of the Society for Technical Communication and serves on the STC’s Nominating Committee.
What this presentation covers
• Reasons for planning
• Documentation plan elements
• Distributing documentation plans
• Summary
6/9/2014 TC Dojo Master Session 3
Reasons for Planning
First things first. Why should you plan?
6/9/2014TC Dojo Open Session 4
Why you should plan
• State the goals
• Specify the details
• Describe the process
6/9/2014 TC Dojo Master Session 5
Why you really should plan
• “It doesn’t matter how you get there if you don’t know where you’re going.”
-- Paul Magid
6/9/2014 TC Dojo Master Session 6
A doc plan answers these questions
• What do you want to write?
• Why do you want to write it?
• How do you want to write it?
• Where will the document be written and produced?
• Who will do the work?
• When will they do it?
6/9/2014 TC Dojo Master Session 7
Doc plan elements
What must you have in your doc plan?
6/9/2014TC Dojo Open Session 8
A typical doc plan has these elements
• Executive summary
• Summary outline
• Overview
• Marketing info
• Production info
• Project staffing
• Project schedule
• Project outline
• Terms of agreement (optional)6/9/2014 TC Dojo Master Session 9
Executive summary
• Two to four paragraphs of text that provide an elevator speech about this project
6/9/2014 TC Dojo Master Session 10
Summary outline
• An outline showing just the chapter/appendix titles with no detail
6/9/2014 TC Dojo Master Session 11
Overview (what, why)
• What will this document be called?
• What type of document is this?
• What is the document’s scope?
• What is the document’s purpose?
• Who is the document aimed at?
• What is the average user’s background?
• What will the user get out of this document?
6/9/2014 TC Dojo Master Session 12
Overview (continued)
• What languages will the document be produced in?
• What are the general assumptions for the project?
6/9/2014 TC Dojo Master Session 13
Marketing info (why)
• Why write this document?
• Competition
• Marketing strategies
• Special considerations
6/9/2014 TC Dojo Master Session 14
Production info (how, where)
• Description of deliverables
• What are the writing and editing standards for the document?
• What format(s) will this document be available in?
• How many pages will this document have?
• What are the art requirements?
• What kind of typesetting will there be?
6/9/2014 TC Dojo Master Session 15
Production info (continued)
• What will the layout be?
• What will the cover art be?
• How many copies will be produced?
• What will be done for the actual printing?
• Are there related materials that need to be produced (such as CDs, templates, one-sheets, quick reference cards)?
• What are the translation requirements?
6/9/2014 TC Dojo Master Session 16
Project staffing (who)
• Writing staff—writers, editors, indexers, etc.
• Design staff—graphic designers, illustrators
• Production coordinator and staff
• Source material experts and reviewers
• Testers
• Localizers
• Instructors (training materials only)
• Individuals responsible for approval6/9/2014 TC Dojo Master Session 17
Project schedule (when)• Project start
• Handoff of 1st draft for review
• Return of reviewed 1st draft
• Handoff of 2nd draft for review
• Return of reviewed 2nd draft
• Final testing, fixes, QA; indexing and TOCs
• Materials released/sent to printer/duplicator
• Return of printed manuals/CDs/DVDs/PDFs/etc.
6/9/2014 TC Dojo Master Session 18
Project outline (what)
• An in-depth outline of the document
• Like any other project outline, assume that the outline will change as the project develops
6/9/2014 TC Dojo Master Session 19
Terms of Agreement
• Responsibilities
– Client’s
– Contractor’s
• Description of deliverables
• Assumptions
• Conditions for renegotiation
(Include this in the Overview section if you’re not using the doc plan as a contract.)
6/9/2014 TC Dojo Master Session 20
Distributing doc plans
Here’s how you get the doc plan out to everyone.
6/9/2014TC Dojo Open Session 21
Distributing documentation plans
• Initial documentation plan review
• Documentation plan sign-off
• Revisions to the documentation plan
– Not every change needs to be signed off, but everything needs to be distributed
– Consider keeping the documentation plan in a read-only format on a server, web site, or wiki for everyone to look at when they want
6/9/2014 TC Dojo Master Session 22
Summary
We’re about done. Here are your takeaways.
6/9/2014TC Dojo Open Session 23
Key points to remember• Doc plans tell you and everyone else what
you’re doing
• Doc plans give you a goal to aim for
• Doc plans make you look good
• Doc plans make everyone accountable (and can also protect you when people decide to make arbitrary changes that will affect you)
• Doc plans give you a tool for post mortem analysis to see how you did
6/9/2014 TC Dojo Master Session 24
Download a doc plan template!• Download a doc plan template at any time:
http://www.hedtke.com/downloads/!blank_doc_plan.doc
6/9/2014 TC Dojo Master Session 25
Master Series: Questions
Contact me at john@hedtke.com
Thank you!
6/9/2014 TC Dojo Master Session 27
John HedtkeDouble Tall Consulting2171 Kingfisher WayEugene, OR USA 97401john@hedtke.comhedtke.comtradebookauthor.com
Feel free to email or write if you have questions.
top related