The power of a doc plan or design doc

For a while, I’ve been thinking about the joys and pains of writing documentation plans (doc plans). It takes a long time to write a doc plan and get it approved. It’s time that you could spend writing the real docs — that is, the user guides, developer guides, API guides, and so on, that constitute our bread and butter as technical writers. Are doc plans worth the time we spend on them?

After careful thought, my conclusion is this:

Doc plans are a technical writer’s power tool. We use them to craft a shared understanding between ourselves and our stakeholders. What’s more, as technical writers, we’re well qualified to write an excellent doc plan.

In many cases, a doc plan does more than define the docs that need to be produced. The doc plan fine-tunes the engineering team’s goals for and design of the product itself. Sometimes, indeed, the doc plan represents the first time anyone has attempted to present a coherent picture of the product’s customers and their needs.

Hint: If your reviewers and approvers are primarily engineers, think about referring to your doc plan as a design doc instead of a doc plan. Engineers know the design doc pattern. They know the purpose of a design doc, and how to review it. This familiarity will make them more comfortable when reviewing your doc plan, and could therefore result in more useful and appropriate feedback.

How do you write a doc plan?

The first steps for writing a doc plan are the same as those for any other document:

Define the purpose and audience of the doc.

Before you start, think carefully about your goals. What you want to get out of the doc plan? What do you want your stakeholders to understand and approve?

If you can’t answer these questions, then maybe you don’t need a doc plan at all. Instead, would it be enough to jump straight into the documentation update and rely on the review and approval process for the documentation itself?

Writing a doc plan should be a purposeful and therefore enjoyable part of your tech writing process. You should feel excited about getting a good, clear decision and about honing your understanding of the problem that your documentation will solve. You should also feel excited about explaining your proposed solution to your stakeholders. If the process of writing the doc plan feels like a nuisance, then the process probably needs changing.

Here’s a summary of how to go about writing a doc plan. The process will probably look familiar, because it’s similar to writing other types of documentation:

1. Define the purpose of and audience for your doc plan. I discussed this in detail in the paragraphs above, and it’s worth repeating here.
2. Gather requirements by reading related docs and specifications.
3. Talk to stakeholders, subject matter experts, and your own team.
4. Scribble diagrams to cultivate your own understanding of the requirements. These diagrams will most likely be user flows that show how people will complete one or more tasks using the product that you’re documenting. Don’t throw these diagrams away! They may be useful in your doc plan.
5. Scribble more diagrams to cultivate your proposed solution. These diagrams will most likely be conceptual illustrations of the information architecture in your documentation site, and user flows showing how people will find and read information in the documentation. Hang on to these diagrams too. They’ll almost certainly be a useful part of your doc plan.
6. Plan the docs that you need, down to the page level, based on the above diagrams. Be aware that the detailed design is likely to change when you start building the docs. At this stage, the page-level detail is useful for estimating the amount of time required to complete the documentation update.
7. Put it all together as a doc plan. The next section has some guidance on what’s in a doc plan.

What’s in a doc plan?

What you put in your doc plan depends on what you want to get out of it. As discussed in the previous section, think about your goals for writing the doc plan. Those goals determine what you’ll include and what you’ll leave out.

Your organization probably has a template or two for doc plans. The internet offers some templates too. I’ve linked to a few templates and examples at the bottom of this post. In my experience, templates are useful as a starting point, but I almost always remove some sections and add others of my own, based on what I need for each particular doc plan.

Here are some useful sections to include in a doc plan:

• Title (for example: ProductFoo doc plan, or Doc plan for migration from Foo to Bar)
• Author
• Summary of the purpose of the doc plan (very short, just one or two sentences)
• Other metadata:
  • Status (draft, under review, approved, etc)
  • Date created
  • Reviewers and approvers
  • Other items that are specific to your environment, such as a short link to the doc plan, your team name, etc
• Introduction (context, including a reference to existing documentation if you’re proposing and update to an existing site, the project or product that the documentation applies to, and other background information)
• Goals and non-goals (a clear description of what you want the documentation updates to achieve, the scope of the documentation updates, and what’s out of scope)
• Use cases (also known as user flows; diagrams are useful here)
• Detailed design for each use case
  • Structure of the documentation site (information architecture; diagrams are useful here)
  • Description of the content required, down to the level of a page (deliverables)
• Implementation phases and timeline (estimates of when the content will be ready for publication, based on an assumed level of staffing)
• Measuring the results (metrics, user studies, and other ways of determining the effect of the documentation delivered)
• Dependencies and related projects

I’ve highlighted in bold the sections where we as tech writers may feel most comfortable and most excited. These are the sections most closely related to the design and creation of the documentation. Yet the other parts of the doc plan are equally important. In fact, they’re key to getting buy-in from our stakeholders.

How comprehensive does the doc plan need to be?

There’s a lot of other information that could go into a doc plan. For example:

• Risks, including assessment of potential impact and mitigation
• A detailed staffing plan (the writer(s) who’ll create the documentation)
• Alternative designs that you’ve considered and discarded
• A plan for translation/localisation of the content
• A log of updates that you’ve made to the doc plan

My recommendation is:

Include only what you need. If you’re not sure, cut it out.

If you’re starting from a template, remove sections that are not relevant. Keep your doc plan lean and mean. This will make for a faster review and approval process. People will feel happier about giving feedback on and signing off something that they understand. If there’s too much content, much of it irrelevant, people will lose track of, and lose confidence in, the bits that are important.

The resulting design, after you’ve incorporated people’s feedback, will be stronger.

What happens after you’ve drafted your doc plan?

After creating the first draft of the doc plan, the goal is to get other people to look at it and give you feedback. This feedback is essential, as it ensures that your understanding of the requirements is correct, and that the documentation that you’ll build will in fact satisfy the requirements.

I’ve found the following strategies useful:

1. Walk through the doc plan with another tech writer, if possible.
2. Walk through the doc plan with your stakeholders. I’ve found that an in-person walkthrough is very helpful, rather than immediately sending the doc plan out for review through email or other asynchronous means. During the walkthrough, you can iron out potential misunderstandings. People can ask you questions, and you can get immediate feedback from people who may not find the time to review the doc plan in detail.
3. Incorporate any feedback from the walkthroughs.
4. Send the doc plan out for review. Include the people who attended the in-person walkthroughs and all other relevant stakeholders. Set a deadline for review comments. A week is usually a good amount of time.
5. Incorporate feedback from the review.
6. Send the updated doc plan out again, and let people know you’re asking for approval. Give a deadline for the approval.
7. Prod people until you have the approval you need.

Now you can start the most exciting phase of all: creating or updating the documentation!

Do you need to keep your doc plan up to date after the documentation is published?

After you’ve published the documentation, do you need to ensure that your doc plan stays in line with further updates? The answer depends on the processes in your specific business environment, but in general I’d say no. A doc plan does have value after the updates are done and dusted, as it shows the reason for the update and the overall design. In most situations, however, a doc plan is an artefact of the consultation, design, and review period of the documentation update. There’s no need to continue updating the plan after the documentation is published. The documentation site itself is the source of truth for current information about the documentation design.

Examples

Here are a few examples of doc plans provided by various people or groups:

• Sample doc plan and template from TechWhirl.
• Doc plan from Tom Johnson at I’d Rather Be Writing.

Any more?

Do you have any examples of, or templates for, doc plans?

Related posts

Since publishing this post, I’ve written a couple of related posts:

• Writing a one-pager to pitch a doc idea
• How to conduct a walkthrough of a doc plan or design doc