Providing accurate and timely project documentation is critical in our world. Each project may require the creation of a variety of documents during its lifespan, and each document may have several stages of release. When the challenge of technically reviewing engineering documentation on your next project, I suggest starting with a series of simple questions to ask yourself. The answers will guide you in a proper review.
Disclaimer: I am not an editor, but I have written and technically reviewed hundreds of documents over my 20+ year engineering career and have picked up a few things that can help you save time and produce better quality project documentation.
- Is this the first time that the document is being reviewed?
- Is the subject matter known to you?
- What is your role in the review? Are you an engineering technical reviewer? Are you a technical writer? Are you a validation or quality representative?
- What stage of the review is the document?
- Is this an initial draft to release a vendor to start or continue work?
- Is this for final approval? Initial release? Operational release?
Is this the first time that the document is being reviewed?
If the answer is yes, then unfortunately you will need to read and review the whole document. If the answer is no, then it depends on the stage of the review that you are in as to how much of the document should be reviewed.
Is the subject matter known to you?
I would argue that the more familiar you are with the subject matter, the more time you should spend on the review. As with the first question above, the effort taken to review the document should be commensurate with the stage of the document development. For instance, a technical writer reviewing an engineering document written by an engineer might not understand the technical content of the subject matter, but brings value to the review by knowing how to convey complex ideas simply, as well as providing grammatical assistance.
When reviewing something that doesn’t make sense, make a comment at that point, and follow up with the author for clarification. They should be able to explain it, and that explanation likely will improve the verbiage used to make it understandable. In some cases, however, the complexity must be kept due to its technical nature. This is ok, providing the document’s audience is meant to be technical. This leads us to the next question.
What is your role in the review? Are you an engineering technical reviewer? Are you a technical writer? Are you a validation or quality representative?
Each of these (and other) roles are part of the review cycle as each of the reviewers brings something different to the table base on their role. Since this article is about engineering technical review, I’ll concentrate mostly on that role. Performing an engineering technical review depends somewhat on the type of document that is under review. A functional specification or configuration specification contains lots of technical jargon, requiring an understanding of both the technical content as well as the structure of the document. Was the document written for GAMP5 processes? Was it structured for S88 batch context? Knowing these will help in your review by knowing the expectations of the document, and ultimately the project.
Compare this to reviewing a standard operating procedure (SOP). An SOP is a series of steps written for an end user to follow along to operate a piece of equipment or run a process. The level of engineering technical review for this type of document requires some process knowledge, and automation knowledge if automation is involved in the SOP. An SOP should be reviewed as if the reviewer were executing the procedure. Review the steps of the SOP to ensure they flow in a logical manner.
What stage of the review is the document? Is this an initial draft to release a vendor to start or continue work? Is this for final approval? Initial release? Operational release?
The review process for each of these options changes based on the stage of the review. Performing an engineering technical review of an initial draft of a document to release a vendor to start or continue work should be thorough enough to capture big ticket items such that the vendor understands the scope of the project without being bogged down with grammatical corrections that will be cleaned up in a more final version. The object of this stage is to get the vendor off and running with the project with a firm understanding of the scope.
Standard Ground Rules to Follow for Every Review
Each of these questions merits varying degrees of engineering technical review and are in many ways intertwined. Here are some standard ground rules that should be followed for every review.
- When using Microsoft Word, ensure that the Track Changes feature is on. Other software may have similar means to track updates and these should be used where appropriate. I know that the Microsoft Excel version of Track Changes leaves a lot to be desired, so I usually highlight cells that I’ve commented upon.
- “Don’t sweat the small stuff,” as quoted in the book Don’t Sweat the Small Stuff, P.S. It’s All Small Stuff by Michael R. Mantell, Ph.D. Reviewing a document doesn’t happen in a vacuum. There are often multidisciplinary reviewers from a wide range of backgrounds and job responsibilities that will catch errors that you don’t see.
- “Don’t let perfection be the enemy of good.” This Voltaire quote was borrowed by a peer and friend on a three-year project we recently finished. If there is verbiage in a document that conveys the idea meant to be conveyed, and it is technically correct, but could be worded just a little bit better (i.e wordsmithing), resist active change. It is good enough. If you think it merits a comment, then reach out to the author. If it is confusing then talking to the author likely will clear it up, without having to make a change.
Be smart about what is being reviewed. Everyone’s time is short, so developing a few guidelines on how to review documents will be key to continued success. Knowing which stage of the document review cycle you are in, whether you have seen the document before or not, and what your role in the review process is, will go a long way to an efficient and thorough document review. Ask questions of the author whenever possible and resist change for the sake of change. Remember, “don’t let perfection be the enemy of good.”
Mark Noseworthy is Senior Project Engineer at Superior Controls, an E Technologies Group company. E Technologies Group is a certified member of the Control System Integrators Association (CSIA). For more information about E Technologies Group, visit its profile on the Industrial Automation Exchange.
