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.
