Writers may hesitate to work with others on content deliverables, and developers may feel that they have little to contribute to the documentation. However, no one can always know everything. So distribute the workload by writing together just like you would collaborate on code. To describe these code techniques, I wrote a book about using code processes and systems for software documentation titled: Docs Like Code. Here are some ideas from my experiences with quality reviews.
When you write for a living, you know you must get advice and input on your writing.
Light&Shadow (1)
In the technical writing world especially, you must ask for feedback. This is called the review process, where another person or system looks at your work and agrees whether the writing can go to the next step in the process. The formality ranges from informal, where one other person may review your work, to military-grade sign-off, where the system must be auditable and traceable. Reviews may provide quality checks, accuracy assurances, legal coverage and protection, a deeper understanding of your content, and ensure that the customer’s needs are met. Reviews make sure that the writing meets a particular standard for consistency purposes. Reviews can double-check one person’s viewpoint of a service or product to make sure that it matches the intended viewpoint or presentation of the product.
What do you think about reviews when you are submitting documentation changes in a code repository?
How do you maintain quality and think about levels of editing while working on documentation in a code repository?
Here are some ideas:
In the traditional writing world, you learn about levels of editing: substantive editing, copyediting, and proofreading. In a software writing world, the substantive editing is the highest value as that is the level where you should check for technical accuracy. These levels of editing also overlap when you are doing a doc review just like a code review. There may be organizational needs, content accuracy checks, as well as proofreading and checking for the standard use of terminology. Train your reviewers to understand levels of editing.
If you have an active reviewer pool, one tip that sounds counter-intuitive is to have your most active reviewers wait. Even if it’s only for a few hours, let the less experienced reviewers have a go at it first. Then involve your more experienced reviewers in the second review. The less experienced reviewers learn when they miss some details or to learn to step back to a wider context. Without examples, these judgement lessons are difficult to teach, so I suggest a waiting period.
Another tip that I really like but have yet to 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 surely helps with this checkbox!
Does the information belong to where it is placed?
Does the change match the shared style guide?
Are the agreed 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 agreed 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, or GitLab, or any other source code system for your documentation.
More information about Docs like Code – the book about best practices for writing using tools & techniques.
[1] Picture source: flickr llee_wu URL
- Git and GitHub for Documentation: Reviews and Quality - 13 July 2017
- Remodeling Documentation - 12 June 2017
