24 Jul Document Review Lifecycle
Document Review Lifecycle
– Sumedh Nene
Editorial Review — the Twin Brother of Writing and a Quality Lifeline
Those who have attended my workshops may find this topic familiar — DRLC. We have all heard of
- Software Development Lifecycle (SDLC), where a software goes from an idea to design, development, and testing to implementation and maintenance.
- Document Development Lifecycle (DDLC), where user manuals and other documents go from audience analysis to design, authoring to editing, and publishing to maintenance.
In line with these two lifecycles, let’s deep dive into a third — the Document Review Lifecycle (DRLC). It is the Editing part in DDLC, where all the quality magic happens; the authored document goes (or should go) through several rounds of review, including self, peer, technical, and editorial reviews as well as legal and sanity checks.
So, you just finished the first draft of your manual and you’ve got all the basics right —attended all the scrums, spoke to the SMEs, researched the user stories, asked all the right questions, and completed the draft of the manual as per the approved structure and table of contents (TOC). Is your document ready for release? Let’s explore this further.
Over the years, I’ve been asking writers, both new and experienced, what kinds of review they do on their documentation. I’ve generally got a fairly consistent reply — editorial and technical. Do you feel these two rounds of review are sufficient? I doubt it very much. I think it is a decent start, but that’s all it is. So, let’s take a closer look at the types of review that should be in place.
Self-Review
The very first in the line of reviews after a draft is complete. This ensures your draft is as good and free of careless mistakes as you can make it before others read it. If you create a checklist for self-reviews (highly recommended), it should include writing, grammar, typos, punctuation, tense, capitalization, updated Index, TOC (and similar lists), the accuracy of cross-references, consistent use of version numbers, headers, footers, compliance with style guides, and so on. Ideally, you should also check for appropriate and relevant screenshots and captions, correct file paths, navigation to various parameters and menu items. Your first draft should only be considered complete after at least one round of self-review.
Peer Review
As the name suggests, these reviews are done by someone other than you and should be similar in scope as self-reviews. Choose reviewers who have an excellent command of the language being reviewed. To closely simulate how a new user (layperson) would react to your documentation, the ideal peer reviewer should not have an in-depth knowledge of the product you are writing about. If finding the time for both self-review and peer review is difficult, you can opt for either one. If you really can’t squeeze in the time for self-reviews, I would suggest that you go for peer reviews. However, if you find yourself struggling to find time for self-checks too often, you might want to pay more attention to your time management and estimation techniques.
Technical Feedback
Technical reviews should be done on a clean copy, free of basic and obvious linguistic issues. Note that technical reviews need to be done by several people, based on their areas of expertise. For example, database configuration sections of a System Administrator’s Guide would be reviewed by a Database Administrator (DBA), while the installation and configuration sections may be reviewed by the likes of a build engineer or a system administrator. Ideally, this round should check the correct sequence of the chapters (document structure), syntax of code snippets and scripts, troubleshooting tips, warnings, definitions, and the overall technical depth. As documents at this stage have not had a thorough editorial review (just a basic peer review), it is a good idea to specifically request the technical reviewers to focus on the technical aspects and not on the format, style, and language. These would get addressed later in the editorial review.
Editorial Review
The peer reviewer may not have been a language expert, but the editor must be! These reviews are arguably the most critical from a writer’s perspective. While the burden of technical accuracy lies on the technical SMEs, the weight of linguistic accuracy rests completely on the writer’s shoulders.
Editorial reviews can be
- Basic. Includes a check on punctuation, spelling, tenses, changing from passive to active voice, and revising run-on sentences.
- Elaborate. In addition to the basic review, it includes a check on inconsistent parallelisms, locale (US, UK), the correct use of acronyms, the adherence to the style guide, capitalization, allowed and deprecated words, and so on.
The review types to be included in a DRLC may depend on factors like the volume of content to be edited, the available time, and the availability of a professional editor. It may also depend on specific client or management requests. It is a best practice to make your own checklist of what is in or out from each type of review according to your needs.
Technical reviews must be done before editorial reviews as substantial changes can be made during the technical edits; moving content or sections around for the correct sequence, significant updates to concepts, procedures, and images to capture technical depth and accuracy is not uncommon. With such heavy edits, editorial reviews ensure there are no unfinished sentences, orphan bullets, or contradictory data between various parts of the manual. Editorial reviews should consider
- Left brain edits. Facts, calculation statistics, values that are either right or wrong and can cause confusion if not corrected. For example, 33 out of 50 is 66%, not 60%.
- Right brain edits. Logic, concepts, or explanations. For example, adding flow charts, descriptions, examples, scenarios, and use cases that make the writing easier to understand.
With all technical and editorial comments addressed, your document should be almost complete, at least on the technical and linguistic fronts. I suggest adding two more reviews, at least for large and complex enterprise applications — legal review and sanity check.
Legal Review
As the name suggests, it should be performed by the Legal department. They should look at the End User’s Licensing Agreement, Registered Trademarks (®), Trademarks (™), Disclaimers, and the like. This is the legal fine print of a manual that writers usually don’t understand.
Sanity Check
For me, this is not a stage, but an ongoing process throughout the DDLC. I track a list of all tasks that need to be done for a document to be complete or release-ready. These can be especially useful when you are delivering a large Doc Suite for the product. I call these sanity checks simply because they help keep me sane during the mad dash of the crunch time before the release date. Create a checklist to track action items against what’s done. Treat it like a landing checklist pilots use to configure the plane for landing. It can be in an MS Excel spreadsheet to track the status of each document (as shown in the image).
Keep adding to this list specific actions as and when you decide to take them. For example, you could add to it the checking in of the latest version to your version control system.
Obviously, there is more to DRLC than what meets the eye. Reviews are a good thing as they are a writer’s friends. Many people work hard to proofread, review, and improve the writer’s work so that the writer can deliver a document that is highly appreciated.
Parting words of wisdom: rather than shying away from reviews as a writer, try and get as many done as you can; they can only do you good.
About the Author
Sumedh Nene has 20+ years of international experience in Technical Communications. He has been helping job seekers of all streams and professions find and get jobs for over 10 years.
This is not his profession, but his passion. Be it newcomers to Canada, people between projects, or those looking for a career transition, Sumedh has helped them use LinkedIn effectively for job search, prepared them for interviews, helped optimise resumes for specific jobs and mentored them on creating attractive portfolios to WOW the hiring managers.
Current Role: Technical Writer, Trainer, Editor, Documentation Specialist
Company: CrackerJack WordSmiths Inc.
City: Mississauga, Canada
Connect at LinkedIn
"Reading maketh a full man; conference a ready man; and writing an exact man."
- Francis Bacon
No Comments