When using docs-as-code techniques, writers might hesitate to work with others on content deliverables, and developers might feel they have little to contribute to the documentation. I assert is that no one can know everything, so distribute the workload by writing together just like you collaborate together on code.
What about reviews? How do you maintain quality while working on documentation in a code repository? Here are some ideas.
GitHub Inline Reviews for Documentation
In GitHub, you send in Pull Requests, which are changes to the files so that you can see the difference between the two files. (See Learning the Vocabulary of GitHub for Docs if you need to know more about Pull Requests.) For docs-as-code, often the files you are comparing are Markdown, where Markdown is the source file that builds the docs site. Here’s an example where the author updates some numbered steps and instructions for more clarity and simpler markup. By clicking on line 20, the reviewer can add a comment – either a single comment inline, or start a new review for the whole Pull Request with a collection of comments all sent in a bundle.
Once the author gets the comments on all the Markdown files, they can make the changes or comment back using the web forms for responses.
For Pull Requests, one best practice is to group your changes logically across only a few files so that the reviewers can look at the changes while keeping other changes in mind. Another best practice is to describe with a bulleted list the changes that are in the pull request so that the reviewer knows generally what to look for while reviewing.
When working with a team, you should also write up your general expectations for reviews in your Contributing file, such as the size of a changeset, amount of expected time for turning around a review and turning around changes, and how to request a review or indicate that a Pull Request is ready for review. The Pull Request section in the Atom Contributing file has good information for you to consider including in your own contributing guide.
Training Reviewers in Docs-as-Code
If you have an active reviewer pool, one tip that sounds like an anti-pattern is to have your most active reviewers wait. Even if it’s only for a few hours, let the less experienced reviewers review first. Then have your more experienced reviewers review second. The less experienced reviewers learn if they missed some small detail or need to learn to step back to a wider context. These judgment lessons are difficult to teach without examples, so I suggest that the more experienced reviewers press pause to give others a chance to try their hand at reviews.
Checklist for Reviewing Docs-as-Code
Another tip that I really like but haven’t yet put into practice formally is to use a checklist. You could start with a fairly simple review checklist, such as:
- Does the document build without errors? Automated testing sure helps with this checkbox!
- Does the information belong where it is placed?
- Does the change match the shared style guide?
- Are the agreed-upon names and terms used correctly?
- Do all the commands in the change work correctly? Here’s where automated testing also helps.
- Does the commit message convey the purpose of the change?
- Does the change claim to fix a doc bug, and if so, have you read the bug and agree with the proposed fix?
Sign up for a series of lessons on treating docs like code, and get a free PDF file of a review checklist for doc changes when using Git, GitHub, BitBucket, GitLab, or any other source code system for your documentation.