Establishing a Review Process

by Zaid Daba'een

One of the most interesting, and difficult, aspects of technical writing is the synthesis of subject matter expertise with the needs of various users. You must simultaneously be the plain-language advocate for the novice user while also ensuring that savvy developers can get everything they need from the documentation. It’s tough, but great documentation provides such myriad benefits when done correctly (reduced support load, increased satisfaction, easier sales conversions), it’s worth exploring all the available assets you have to get it right. Having an ironclad review process is a surefire way to progress in that direction, but your review process is likely constrained by time and the schedules of your team members. So, how can you design a review process that’ll be efficient, make end-users happy, and properly leverage your team members’ time?

While there may not be a hard-and-fast rule for review processes, the following guiding principles are a great start for getting your documentation in top shape:

  1. Broad, focused documentation reviews
  2. Documentation that lives with the code
  3. Easily accessible, standardized access

Let’s take a look at each of these individually and how they can apply to your documentation review process.

Broad, Not Deep

Your team members are often specialists in their respective fields, and they should be leveraged as such. Rather than dropping your work into their routine with a vague intention of “making the docs better,” ensure that each reviewer knows what their contribution should be. Let the QA reviewer focus on the known issues that may be absent from the document. Let the Marketing reviewer focus on ensuring the branding and voice of the writing align to the larger goals, and so forth. By having a broad pool of reviewers each with specific, specialized goals, you are able to get the best aspect of each team member while minimizing redundant reviews. Personally, my worst reviewing days have been when I receive six emails back from subject matter experts all pointing out a minor typo or JSON structure issue but no feedback on some of the truly difficult nuances of the feature or API. Everyone is pretty fatigued by the time the document comes back around, and even when the second pass is more intentional, the quality suffers. Likewise, each reviewer should be able to expect when the review will come their way. In my experience, I typically move from design to developer to marketing reviews to ensure accuracy as the focus and document develops. Figure out the singular but focused role each reviewer has and you’ll save time while improving your docs (and potentially watercooler chats too!).

Two-Way Documentation

While standard help center articles typically only surface once the feature is complete, many API documents grow and live with the APIs in the codebase itself. Design or contract-first API methodologies are growing in popularity and continue to be useful in ensuring that critical partner or internal features are at the forefront. Design-first API methods focus on the contract (or human and machine-readable document) and only then build the supporting code, while code-first approaches focus on directly coding in the API from which the contract is later generated. Tracing the current trends, a 2019 State of the API survey found that “while 25% say they are only using a design-first approach, 22% say they are using both the design-first and code-first approach. One-third of the respondents that currently use code-first only say they are moving to a design-first approach.” As such, a key takeaway is that great documentation also adds value back to the design itself.

Personally, I have worked in typical sequential review flows where a raw JSON file is passed to me, I edit and publish it, team members sign off on the new version and the document is largely filed away never to be revisited. The improved documentation never makes its way back to the code comments and future developers and writers miss out on the fruits of the review process. In some cases, the discrepancy can grow between the internally-held and externally-published documents to where there are significant enough differences to impede the full utility of the API; for example, when an endpoint is being refactored, insights gleaned from prior iterations are left out. In companies with significant turnover or growth, new team members or developers may be referencing the same doc from different sources and creating confusion. Making sure that your reviewed, improved copy is the benchmark document allows your team’s hard work to reach its full potential.

Standardized Access

One of the most simple yet easily overlooked aspects of a good review process is the ease of access and drafting. Nothing torpedoes a review process more quickly than having half of it in shared docs, part of it in emails or chats, part on the live site, and so forth. Choose a specific method for drafting and reviewing and stick to it. This will not only save you many organizational headaches, but it will also prevent key edits being lost in the mix of multiple drafts and locations. Personally, I love the new addition of Reviewer roles in DeveloperHub for this very purpose. Developers and QAs can get involved in the same document and leverage different versions to keep the edits intact. Likewise, the finer parts of discussion can be handled with in-app comments before being instantly published. Edits can be reverted at any time to remove any pesky errors, so I can be sure that we can dive into the process without concerns of losing any key feedback.

When it comes to establishing your review process, an ounce of planning is worth a pound of cure. Let me know if any other steps have made your review cycles much better (or worse!) in the comments below. Happy reviewing!

Written by Cody Holden for DeveloperHub.io.