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.