|
By: Sumedh Nene
You just finished writing a successful guide. You’re exhausted, and almost satisfied. You’ve got all the basics right—you reviewed the document yourself and put it through technical reviews as well. Why then not completely satisfied? Patience, my friend, I’m getting there.
Before that, let’s quickly look at what I mean by a successful document. As a reader, what in a technical manual makes you go, “Whoa, this manual is awesome, man! It actually makes sense and I could also find what I needed, easily”? Doesn’t happen too often, does it? That’s because not all technical documentation is designed and structured to incorporate the four features of a successful document:
• Can the reader FIND the required information?
• Can the reader UNDERSTAND the information?
• Is the information COMPLETE?
• Is the information ACCURATE?
We’ll deal with how to design and structure a document for all these features at a later date. For now, let’s just get back to our discussion on reviews.
The only way to ensure you have captured all the data in the best possible way is through reviews. So, do you feel that just two rounds of reviews—your own edits and a technical round by a developer are enough? I doubt it very much. I think it’s a start, but that’s all it is.
Over the years, I’ve asked a lot of writers, new and experienced, what kinds of reviews their documents go through, and I usually get the same answer: editorial and technical reviews. So, a few of us brainstormed on the review cycles and types of reviews a document can actually be put through—on the lines of SDLC and DDLC. Let’s refer to the reviews as the Document Review Life Cycle (DRLC).
Self Review: This must be done before any other review. This round ensures your draft is as good as you can make it, before others read it. Issues to watch for in this review should be writing, grammar and style related, for example, typos, punctuation, tenses, capitalization, and so on.
Consider reviewing structure and design errors, for example, updated Index, TOC and other lists, accurate cross-references, consistent use of version numbers, headers and footers, and so on. Though you may not do full justice, it will be ideal to double-check the document for technical accuracy as well, for example, use of appropriate and relevant screenshots, and proper paths of files and parameters. Your first draft is complete only after a round of self review is complete.
Peer Reviews: To be completely confident of what you’ve written, you can use peer reviews as an additional review cycle. On occasion, you could consider skipping a cycle of self reviews and replace it with 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. As the name suggests, these reviews are done by someone other than you and its scope should be similar to that of self reviews. Choose reviewers who have an exceptional grasp of the language to be reviewed. To simulate how a new user (layman) would react to your documentation, the ideal peer reviewer should not have an in-depth knowledge of the product you’re documenting.
Technical Feedback: Once a self check and/or peer reviews are complete, the next round should be of technical feedback. 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 should be reviewed by the DBA, while the installation and configuration sections should be reviewed by the likes of a build engineer. Ideally, this round should include the document structure (proper sequence of chapters), syntax of code snippets and scripts, enhancing the contents with troubleshooting tips and warnings, definitions of glossary terms, and the overall technical depth.
Since documents at this stage have not had a thorough editorial review, it’s a good idea to specifically request the technical reviewers to focus on the technical reviews rather than the writing and linguistic issues (which get addressed later in editorial reviews).
Editorial Reviews: While the peer reviewer may not have been an English expert, the reader of the next review cycle, that is, editorial reviews, must be. Note: English is used here for simplicity; it denotes any language of documentation. These reviews are possibly the most crucial from a writer’s point of view. While we do know that in the entire document, the onus for technical accuracy lies on the technical people to some extent, the language accuracy is completely the writer’s responsibility.
Depending on several factors, such as your release date, volume to be edited, availability of a professional editor, you may choose to have a basic or an elaborate review cycle. Make your own check list of what you would want to include in each of these categories based on your requirements.
• Basic review can range from basic spell check, proper punctuation, and checking tenses, to changing from passive to active voice, and improving sentence length and structure.
• Elaborate reviews include the basic reviews and things like eliminating faulty parallelisms, checking for locale (US, UK), proper use of acronyms, consistent use of a style guide, and so on.
The editorial and technical reviews you received till now generally require you to make two types of updates to your documents:
• Content Updates: Correct the inaccurate left-brains facts (statistics, values, and specific inputs) that can cause confusion if not corrected. Enhance the right-brain explanation (such as examples, description, and so on) to make the writing easier to understand. Add essential information that was left out and remove obsolete features.
• Structural Updates: Rearrange chapters and paragraphs for proper sequence and a more logical approach to the product.
By now, your document should be almost complete—on technical and linguistic fronts at least. If you are not yet satisfied, consider another pass at technical and editorial reviews. What remains are a couple of more reviews that are often neglected. These are Legal Reviews and a Sanity Check.
Legal Reviews: These reviews should be done by the Legal department. They include End User’s Licensing Agreement (EULA), Registered Trademarks (®) and Trademarks (™), Disclaimers and the likes.
Sanity Checks: The final review should ensure there haven’t been careless updates or changes to the document, and all the tasks that need to be done for the document are complete. These are termed as sanity checks. Ideally, you should create a checklist that you should run through, just before the document is checked in for the final time.
Your checklist should include updating the Index, TOC, and other lists, removing watermarks and draft markers (for FrameMaker), version numbers, headers and footers. Consider using a single Excel spreadsheet to track progress of all documents in your documentation set. Here is a sample check list, done in Microsoft Excel.
You should keep adding to this list with 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.
So, as is obvious, there is more to reviews than meets the eye. Reviews are a good thing-they’re a writer’s friend. Many people work hard to proofread, review and improve our (the writer’s) work, and we deliver a document that is highly appreciated, we generally enjoy the limelight. 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.
|
Events
