Before you go, join the Friendly Docs Society!

I don't email often, but when I do, it's good stuff (if I do say so myself).

I will never send you spam. Gross. Unsubscribe at any time.

Powered By ConvertKit

Managing Documentation Reviews

managing documentation reviews (2).png

I love reviews of my work. When doc reviews draw near, it's like Work Christmas: I'm nervous and excited as I start to dream of all the comments I'll get back. Will people like the design? I wonder how many typos they'll catch... I hope they notice how careful I was to make the wording consistent! I really hope they catch a couple of errors, so I'll know everything else is definitely right....

Then the dread sneaks in: what if no one responds? When I don't have good feedback (or, almost worse, I get the single phrase "looks good"), it's hard to know if my work provided any value at all. I'm a perfectionist about my work, but I'm not delusional: there's definitely something wrong in there. Not even NASA gets it perfectly right the first time. But after weeks or months of staring at the docs, my eyes glide right over the problems. I know mistakes are there, and I need the team to help me find them.

For code, we have exhaustive testing of every function, every release. But in the sprint to catch the next person in the Agile relay (or to dive headlong across the tape in Waterfall), documentation reviews often fall to the wayside. But failing to test the docs is just as short-sighed as failing to test the code. The docs are our customers' companion as they traverse the world of the release. Good UX is a godsend, and flawless programming is great, but if you find yourself stuck on a desert island with a well-designed and thoughtfully constructed raft, you'll still want the instructions to know you're putting it together properly.

That we need buy-in for doc reviews is obvious. But how can we get it? Well...

Setting the Stage

State your case

No one is going to know how important it is to review the docs if you don't tell them. Call together the core team - the Project Managers, Business Analysts, UX Designers, and Developers - and share why it's so important to review the docs.

Download the Documentation Reviews Slide Deck

Use these slides to help your team understand the documentation review process: why it's important, how to do it, and what to focus on.

    I won't send you spam. Unsubscribe at any time.

    Powered By ConvertKit

    Even if you decide to make your own, the next steps are the same: invite your team to a meeting to discuss doc reviews. Remind them why we have docs, and why it's just as important to review them as it is to QA the software. Make sure they know who needs to be involved in the review, and help them understand what you need when you send a review package.

    I recently had the chance to A/B test my slide deck, and the results were shocking. Among the team members who attended the meeting, I received a 100% response rate to subsequent review packages. Among those who didn't attend the meeting, I received a 25% response rate. Helping your team understand what you need and why is crucial to getting the feedback you need to be successful.

    Get Specific

    While you've got your captive audience, help them understand exactly what you need. The deck has slides with suggestions, but at a minimum, I'd cover the difference between more and less helpful review comments, how fast you expect SMEs to respond before you move on without them, and whether you'll conduct multiple rounds of reviews.

    No matter what specifics you settle on, the most important thing is to set the team's expectations. You can and should get their feedback to make sure everything you need is in line with what's possible (and push back on management if it's not). Everyone needs to know what's happening before you can expect them to do it.

    Get Management Buy-In

    It's good to get individual team members on your side, but it's even better to get management. One of the people who attended my doc review meeting was a manager. After the meeting, he not only provided a quick review of the docs, but he also began working behind the scenes to integrate me into the larger development process.

    Although I was happy to have good buy-in from the Business Analyst who attended, this manager (my manager, as it happens) has been crucial in changing company culture to integrate the docs. He's bringing in others at and above his level to find ways to bake me into their processes, including making doc reviews a hard stop in the sprint schedule the same way that code regression is. I couldn't buy better publicity for my work, and his buy-in is encourages other manages to buy in as well.

    Getting Down to Business

    Iterate, Iterate, Iterate

    Once you've convinced everyone how important it is to review the docs, take a page from Agile and begin iterating on your work. Just like in the Agile process, start small: is this the right outline? Am I covering the correct topics? Better to get a "no" now than when you've already written 25 pages. (You can also check your work against the sprint user stories, if you have access to them.)

    When you have your outline approved, then and only then do you begin writing. Send each topic for review as you complete it. It's a lot harder for SMEs to review a 100-page doc that they've never seen before than to review a 4-page topic. Similarly, it's hard to rewrite 100 pages that you got mostly wrong than to rewrite 4 pages you got mostly wrong.

    Break down your work into chunks that can be reviewed quickly at each step in the process and have SMEs review those: topics outline, topics design, individual topics, then the whole shebang. This will work in Waterfall development too, but a quick iteration cycle is especially important in Agile projects where there's little run-up time to get projects running. Also, others on your team will likely understand the iteration cycle better and more intuitively if they're already familiar with Agile.

    Track the Reviews

    Don't just leave your reviewers hanging on a limb; give them some structure to cling to. I like to provide a spreadsheet that provides basic information with dropdowns: which document did they find a problem in? Which section? What kind of problem? It helps them be specific, which helps you quickly tackle the issues they find.

    It can also be helpful to provide more general spreadsheets tracking overall impressions of the document. Tech Whirl has some great spreadsheets of the more general type here. Sending both the specific and the general can help make sure you cover all your bases, assuming you've properly prepared your SMEs for reviews in the doc review meeting.

    Best of luck in your doc reviews!

    Don't forget to download the Documentation Reviews Slide Deck!

      I won't send you spam. Unsubscribe at any time.

      Powered By ConvertKit

      Join the Friendly Docs Society!

      I don't email often, but when I do, it's good stuff (if I do say so myself).

      I will never send you spam. Gross. Unsubscribe at any time.

      Powered By ConvertKit