Blog Archives

Role of a technical lead (TL)

What does a technical lead (TL) do in a technical writing team? How does the role of a TL differ from that of a manager, or from that of another technical writer? In this blog post, I hope to answer those questions and to start a discussion where others can add their thoughts too.

I’ve been TL of a technical writing team for a couple of years. In fact, my current team includes people working in several roles: technical writers, developer relations engineers, instructional designers, and program managers. In the past, I’ve also been TL of a team that consisted solely of technical writers.

The TL role is interesting, challenging, and rewarding. I think the first thing to be aware of is that the role varies depending on multiple factors: the structure of the organization you belong to, the size of the team, the nature of the documentation and other content that you’re looking after, the audience for that documentation, and most importantly, the people in your team.

With all of that in mind, I’ll describe my role as an example.

What does a TL do?

A technical lead ensures that the team’s goals are in sync with those of the stakeholders, that the team can work happily and efficiently, and that everyone knows what’s going on.

In my experience, the most important (and most time consuming) part of the TL role is communication. As a TL, everything you do involves communication, whether you’re planning the team’s work for the next period, keeping your stakeholders informed about the team’s progress, or keeping the team informed about things that are happening around them. So let’s start there.


As a TL, I see myself as having two major communication goals.

A moth on the outside looking in.

The first goal is to keep my management chain and the product-area stakeholders informed about the work that the team is doing. What are our goals, how are we tracking against those goals, and what have we produced recently?

I do this in various ways, including the following:

  • Write and then talk through informal periodic (e.g. monthly) status reports at pre-scheduled meetings. These meetings are very useful for me as well as for the stakeholders, as an opportunity to get instant feedback on progress and to ask questions about prioritization and overcoming blockers.
  • Contribute snippets to periodic formal reports (sometimes called news letters) for higher-level leadership. This type of reporting is often onerous, as the content needs to be more strategic in nature than the informal status discussions and has constraints around format and length. If you can use existing templates or get the help of others in compiling these reports, so much the better!
  • Ensure that we as a team publish announcements of our launches or other successes, using whatever channels are best suited in our environment.
Patterns made by crabs on a beach.

The second communication goal is to keep the team informed about the strategies and goals of our management team and of the product and engineering teams who’re building the product that we document.

The team is a unit, working on a subset of patterns that fits into a larger set of patterns. It can be hard for people to know how they and their work fit into the larger pattern. The TL’s role is to help team members see the patterns.

A few tips about communication:

  • Err on the side of over-communication rather than under-communication. People may miss a message because they’re away or just too busy to pay attention right now.
  • Use multiple communication channels: Email, chat, meetings, planning docs, and so on. People absorb information in different ways.
  • Avoid falling under the curse of knowledge: that predisposition, shared by all people in the know, to omit what seems obvious. This predisposition makes it almost impossible for experts to explain something to a new starter. As technical writers, we’re very aware of the curse of knowledge. We know that the documentation needs to include information that may seem obvious to our subject matter experts. As TL, though, you might find yourself falling under the curse of knowledge too. You’re aware of activities and messages that your team and stakeholders don’t know about, but it can be hard to remember that they don’t know. When you receive an item of news, share it with everyone who might find it useful.

Building a framework for other people’s success

Another essential aspect of the role is creating a framework in which the team members can succeed. I find it helpful to remind myself of this goal, because it helps me to focus on the important elements of my role.

Part of creating that framework is to do regular and thorough planning of the team’s goals. Help people understand where we’re headed as a team.

Planning of team goals

In my current team, we do in-depth quarterly planning as well as high-level annual planning. The annual goals tend to be more strategic. They set the pattern for the quarterly, tactical goals.

For our quarterly goals, we use the OKR framework. OKR stands for Objectives and Key Results. We use the objectives to reflect our strategic goals. Often an objective corresponds to a theme in our annual strategy — something like “Improve the getting-started experience” or “Increase adoption of product X”.

We group our key results under the various objectives. Key results are more tactical (more task-like) and reflect goals that we aim to achieve within the quarter — something like “A design doc approved for user journey X” or “80% of onboarding docs complete”. So, an objective might stay the same across multiple quarters, while the key results grouped under it will change from quarter to quarter.

As with everything, communication plays a key role in the planning. As TL, I need to consult our stakeholders and management team, to find out what their goals are. I consult my team members on the details of their long-running goals and shorter-term goals. I put together draft OKRs, then review them in person with multiple groups of people before coming to an agreed set of goals for the quarter.

Of course, the job doesn’t end once the OKRs and strategic plans are created. We need to do periodic assessments of progress against the original plans, make adjustments where necessary, communicate those adjustments. If some goal has been significantly derailed, the TL is the one who’ll discuss readjusting priorities and communicate the results to stakeholders, management, and the team.

Creating specifications for junior team members to work from

Another aspect of building a framework for success is to create requirements specifications and design docs that the more junior team members or new starters can implement. As a TL, it’s often the case that you won’t be the one writing the docs even if you’ve done the analysis and design. Instead, you’ll hand the specifications over to another writer or group of writers. This is especially true if you have new team members who don’t yet have the depth of product knowledge required to design a significant doc update. I’ve touched on the topic of design docs and doc plans in two earlier posts: The power of a doc plan or design doc and Writing a one-pager to pitch a doc idea.

A content strategy doc is often useful to set high-level goals and define strategies for meeting those goals. For example you might create a content strategy doc to help the team and stakeholders outline the goals and strategies for the coming year. Or you might define a high-level strategy for a particular product area or user journey. Other team members can use the strategy doc as a basis for more detailed planning and designs.

I could write an entire blog post about content strategy docs. I’ll leave that for another time perhaps!


Another important part of a TL’s role is mentoring of team members. Mentoring isn’t confined to the TL role: any team member can mentor others. But for a TL, it’s a logical, natural part of the role. Typically, this type of mentoring involves working with team members to manage priorities, smoothing out any technical problems the team member may encounter, advising them on how to communicate with stakeholders, and helping the team member to decide whether a particular issue is on that they should take to their manager.

I think that the most important goal here is to help people find the best way to be successful in their roles. That means helping them figure out how best to complete their assigned tasks and making it clear to them that you’re available to offer advice.

How does the TL role differ from that of a manager?

Although much of the TL role involves working with team members, a TL isn’t a manager.

A Hakea seed pod, which reminds me of the Yin Yang symbol.

The focus of the TL is on the projects that the team is responsible for. The focus of the manager is on the people in the team. The manager helps team members reach their career goals and navigate any organizational complexities.

In reality, there’s no hard line between the two roles. The TL and manager need to consult often. They work as a leadership team, sharing responsibility for the well-being of the team.

In particular, TL and manager work closely together on strategic planning. The high-level planning affects the well-being of the team members, the assessment of the team size and the potential requirement to add more people to the team. High-level planning incorporates goals that stem from tech writer management as well as from the product areas whose docs we’re responsible for.

Many organizations have a hybrid Tech Lead / Manager (TLM) role, which is a blend of the two roles. The TLM role is all-consuming, and works only for a small team (fewer than 10 people) otherwise the TLM is swamped.

How does the role of TL differ from that of another technical writer?

Looking across the opening of Sydney Harbour towards the Pacific Ocean.

If you’re a singleton technical writer (that is, the sole technical writer working with a product team on a set of documentation), there are many similarities between your role and that of a TL. Singleton writers have to do a lot of planning and communication. The main difference is that they’re doing it for their own work only, not for a team.

Both TLs and singleton writers face a similar problem: how do you fit in any work on the actual documentation, when you’re spending so much time planning it, reporting it, and communicating with everyone?


A Huntsman spider on a biking map. The spider is on the inside of the glass, and my finger is outside.

The TL role can be a tough one. I hang on to the fact that by doing this role well, I’m guiding others through the tricky bits of a technical writer’s role and helping managers and stakeholders do their job too.

My top tip is to make sure you find the time to do the things that make your job rewarding for you. Make this part of your prioritisation exercise. It’s important.

For me, the best part of the technical writing role is when I can focus on the documentation and the users’ experience of the product through that documentation. If I can get in the zone for at least part of the day, by fixing doc bugs, or designing major doc updates, or best of all by actually writing a doc that helps a user accomplish a task, then I’m happy at the end of the day.

A happy TL makes for a productive team.

Another top tip is to learn the art of saying no. It’s actually helpful to stakeholders and other leads when you give a clear “no” backed up with reasoning and an explanation of the higher priorities that the team is currently working on.

Potentially, you could soften the blow with a suggestion on how the stakeholder can add the task to the queue for prioritisation in the next quarter. If the stakeholder judges the requested task to be of higher priority than current tasks, work with that stakeholder and the product leads to decide which tasks can be deprioritised. Include an estimate of the amount of time wasted when the technical writer(s) have to switch context and ramp up on a new task.

Wrapping up

What have a missed? Let me know. 🙂

Card sorting for user journey analysis and information architecture design

Recently I’ve been using a card sorting tool, part of the Optimal Workshop toolbox, to analyse a set of user journeys. The card sorting tool is also useful for designing an information architecture for a website or documentation set. This post describes how I used the card sorting tool, because it may be useful to other tech writers and information designers. (I’m not affiliated with Optimal Workshop, nor have they asked me to write this post.)

I’m working with a team to design a tool for gathering and presenting documentation metrics. As a first step, we want to know what type of metrics people will find useful, and how they’d like to use those metrics. We decided to start by gathering user journeys. For us in this context, a user journey is a goal that someone wants to meet by following a set of tasks.

After gathering the user journeys, we needed a way to analyse and collate them. Optimal Workshop‘s card sorting tool came in useful here. This post describes how.

Note: The examples in this post come from Optimal Workshop’s demo application. (They’re not from the actual interviews and user journeys that my team is working with.)

This screenshot shows an example of a card sort, from Optimal Workshop’s demo application:

In the above example, participants in the card sorting exercise can move the cards from the column on the left into the work area on the right. When moving a card, participants can choose to put a card into an existing group, such as “Buying a cell phone”. Or they can create a new group and give it a name.

Context around what I needed to do

My team’s goal was to understand a large set of user journeys that we had collected for a yet-to-be-designed system. Before using the card sorting tool, my team had done the following work:

  1. Interviewed prospective users of the proposed system, asking them a set of open-ended questions about why and how they would use the system.
  2. Made notes during the user interviews, using a standard template to ensure that each interviewer captured the same sort of information from each interviewee.
  3. Distilled the notes from each interview into one or more user journeys. A user journey encapsulates a single goal expressed by the user. It may take one or more tasks to achieve that goal, but at this point the goal was the important thing.
  4. Collected all the user journeys into a single repository. In our case, we used a spreadsheet.

After doing all that, we had a large collection of user journeys — too many to work with in the next phase of the project, which is to prioritize the use cases, define requirements for the use cases that we want to tackle first, and design a minimum viable product. Some of the user journeys were duplicates. Some user journeys represented subsets of others. Some user journeys expressed a similar goal, but from a different perspective.

We needed some way of analysing and collating our user journeys. Enter the card sorting exercise!

What is card sorting?

Card sorting is an exercise that you can use to see how your customers think about a certain subject area or product. You give people a set of cards, each representing an activity, task, topic, or concept, and you ask them to group (sort) those cards into categories.

I’m using the word customers in a broad sense. The participants of a card sorting exercise can be customers, users of a product, readers of a website, members of a design team, and so on.

As the creator of a card sorting exercise, you can choose whether to give your customers preordained categories (a closed card sort) or to let the participants make up their own categories (an open card sort).

By examining the groupings made by the participants, you get useful insights into the way people think about your subject area or product.

In the past, I’ve participated in card sorting exercises where we used real cards made out of paper or cardboard. Sometimes the cards were Post-it notes. We’d write the topics, tasks, or concepts on the cards and place them on a table or stick them on a whiteboard. Then we’d shuffle the cards into groups, using the exercise as a way of exploring concepts and designs.

It’s quite common to use electronic cards instead of paper ones. That’s what we did for the user journey analysis that I’m describing in this post, using Optimal Workshop.

How we used card sorting to analyse our collected user journeys

We decided it’d be useful for each member of our team to analyse the user journeys individually as a first step. That’d give each of us the freedom to look for patterns and understand the users’ goals, without being influenced by other members of the team. After that, we wanted to analyse and collate our findings.

I loaded all the user journeys from the spreadsheet into Optimal Workshop’s card sorting tool. I created an open card sort, so that each person could make up their own groupings of user journeys. Then each team member spent a couple of hours sorting and grouping the user journeys. You can see what this looks like by trying Optimal Workshop’s demo app, using the participant view.

The next step was to examine what we came up with. Optimal Workshop offers some useful tools in the Analysis tab of the Results section. To try it out, see the results view of their demo app.

In particular, I found the 3D cluster view interesting and useful. Here’s a screenshot from the Optimal Workshop demo:

The tool analyses the categories created by the participants, and further groups the categories into clusters. This is particularly useful in an open card sort, where participants have created their own categories. It gives you a way of finding similar categories.

The next screenshot shows the details of one particular cluster, listing first the categories in the cluster, and then the cards in those categories:

We used the sets of “similar category labels” offered by the tool as a starting point to help us combine and reduce the number of user journeys in our collection.

Card sorting for information architecture design

In the situation that I described above, we used card sorting to analyse user journeys. Card sorting is useful in other situations, one of which is designing the information architecture (IA) of a website or a documentation set.

The IA usage is closer to what Optimal workshop’s demo application shows. In case you skipped past the section of this post about user journeys, here are the links again:

  • You can try out Optimal Workshop’s demo as a participant in the exercise, using the participant view.
  • Or you can try it out as the analyst or designer viewing the results of the card sorting exercise, using the results view.

Card sorting is also useful for the members of a team designing the website. Instead of having users do the card sorting exercise, you can have your team do it. This gives each person the freedom to draft designs in peace, play with concepts, and experiment with new groupings. Once everyone has finished, you can get together to see the differences and similarities in the way you’re thinking about the design.

Trying out Optimal Workshop

You can use Optimal Workshop for free to try it out. See the various options on their pricing page, including “try for free”.

More tips about card sorting or other UX tools?

If you’ve used a UX tool as part of your role as technical writer or information designer, I’d love to hear about it.

Writing a one-pager to pitch a doc idea

As a technical writer, I’ve sometimes found it useful to write a short document describing an idea or a proposal. The target length for such a document is one page. Hence the name, one-pager. In some situations, a one-pager is a good alternative to a doc plan.

This post is about one-pagers used in the context of technical writing. In other contexts, a one-pager may be a pitch for a company or a student’s summary of a lecture.

Quip: An engineer pointed out that one of my one-pagers was technically a two-pager. (It was actually about one and a third pages long.) I responded that I could fix that by reducing the font size. 🙂

For me, the purpose of a one-pager is to express an idea and get input on the idea. For example, I’d write a one-pager when a doc plan would be too heavy-weight, but I want to get feedback before starting the documentation update.

A one-pager isn’t the place for a detailed design — that’d go in a doc plan or a design doc. (See my post about doc plans.) Rather, a one-pager is useful to coalesce my own thoughts about an idea, and to get feedback from my colleagues about the overall idea before I go ahead and implement it.

For example, I’d create a one-pager to propose one of the following:

  • A new tutorial for a use case that we don’t yet cover in the documentation.
  • A new type of tutorial that follows a different pattern from the other tutorials in the documentation set.
  • A change of tone in a particular document or documentation set. I’d describe the tone of the current documentation, the effect that the tone is having on readers, the new tone that I’m proposing, and the reason for the change.
  • An event, such as a doc sprint. I’d describe the purpose and format of the event in order to gauge support before plunging into further planning.

What does a one-pager look like? Well, firstly, it’s short and to the point. Because it’s so short, a one-pager often doesn’t include headings. My one-pagers tend to look like this:

Title (For example: One-pager: New tutorial type for Foo users)
Date and author

Goals: A business statement of the effect you want to achieve. (For example: customer retention, increased adoption, etc.)

A short, motivational callout, often in large text and a different style from the rest of the doc. (For example: We want to help customers use Foo when things go wrong.)

A succinct description of the idea or proposal. This is the main part of the one-pager. Start with a descriptive paragraph, followed by bullet points to capture the main points in your proposal. As well as being a useful short form, a bulleted list gives visual emphasis that this is the core of the one-pager.

In scope: Areas that are in scope for this proposal. If you don’t have anything to put here, leave out this section.

Out of scope: Any areas that are out of scope. The goal of this section is to ensure there are no misunderstandings between you and your stakeholders. If you don’t have anything to put here, leave out this section.

References: a list of relevant documents

Have you ever written a one-pager, or have you felt the need of such a document type in the past?

How to conduct a walkthrough of a doc plan or design doc

In a recent post about writing a doc plan or a design doc, I mentioned that it’s useful to conduct one or more walkthroughs of the doc plan or design doc before sending it out for review. Here are some tips on conducting a walkthrough.

During an in-person 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 in detail.

In other words, a walkthrough can help clear away the cobwebs! I took this photo recently while walking on a bush path.

Inviting people to a walkthrough

The first step is to decide who should attend your walkthrough. If you have the luxury of working with other technical writers, it’s useful to walk through the doc plan with one or more of them first. They’ll point out inconsistencies, missing pieces, and unclear sections for you, and help you crystalise your own understanding of the problem that your design is solving and iron out any wrinkles in the design.

Give yourself time to incorporate feedback from the technical writers before holding the next meeting.

Next up, invite your key stakeholders to another walkthrough. These people should be the ones who can give you input on the problem and on your design. For example, your product manager and the engineers responsible for the area of the system that your documentation will cover.

Schedule at least a full hour for the walkthrough. The time will shoot past once everyone starts discussing the use cases and design.

In the invitation, provide the link to your doc plan, but don’t expect people to read the doc plan before the meeting. Some of them may look at it, but you should assume that no-one has seen it properly.

Running the walkthrough

Your goal for the walkthrough is to ensure that people understand what you mean to convey in the doc plan. Until you’ve run the walkthrough, you can’t be sure that what people will get from reading the doc plan matches what you intended to say.

I’ve found the following format useful for a walkthrough of a doc plan:

  • Start by explaining purpose of meeting: to give the attendees an overview of the doc plan and the design that it proposes, and to gather preliminary feedback. Let the attendees know that you’ll send the doc plan out for detailed review after the walkthrough.
  • Describe the context of the doc plan: the problem that you’re looking to solve, and the customers who form your target audience.
  • Show the outline (table of contents) of the doc plan, so that your attendees know the scope of the doc.
  • If the doc plan is very long, decide beforehand which sections you’ll walk through in person. Often, the diagrams (user flow and information architecture) are most useful sections to cover in person. Also make sure you cover the timeline for delivery of the documentation.
  • Actively solicit feedback at all stages of the meeting.
  • Make copious notes, either as comments in the doc plan or in a separate document, during the meeting. Do this note taking yourself — don’t rely on others. Your attendees won’t mind your making notes, as it shows that you care about their feedback. Other note takers don’t have the depth of context that you have, and they may miss important items.
  • After you’ve walked through the sections of the doc plan that you intend to cover, make sure you sit back, relax, and give everyone time to think about the bigger picture. Often the most useful feedback comes at this stage, when people know they’ve seen all that you want to show them, and they can think independently.

After the walkthrough

Update the doc plan to incorporate the feedback that you’ve received. If necessary, change your design to match your new understanding.

Finally, send the doc plan out for review, by email or using whatever channel your organisation uses for this type of review. Make sure you send it to all the people who attended your walkthroughs, as well as to other stakeholders and team members.

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.


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

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:

%d bloggers like this: