[Disclaimer: The article has featured previously in TechCraft and its copyright is with the author, Girish Sharangapani.]
“Ink is better than the best of memory!”
Extending the thought behind this old Chinese proverb to suit the modern-day documentation specialist, I’d say, when it comes to product documentation, it’s extremely important for you to put ink on paper in a thoughtful manner for a long-lasting effect.
According to me, the key to an effective and good quality document is a thorough review process—one that verifies the accuracy of your content. You could call this process by different names; be it self-review, peer review, structured walk-through, or whatever. A lot has been written about these processes. This article does not cover any of these, but touches upon the basic essence of a document review process—its importance, and the value it adds to your product and business.
Over the last decade or so, there has been a paradigm shift in the mind-set of senior management across various industrial verticals with respect to product documentation. More and more people have started to believe that product documentation is as important as the product itself. However, even as I write this, many product documents, especially those that cater to the software industry, smack of extremely poor quality, in spite of the numerous quality measures adopted by organizations.
The problem is people still do not perceive good quality product documentation as an integral part of their business. The general notion is that documentation doesn’t add to their revenues in the long run. However, the reality is far from it: an outstanding document can even make a mediocre product look good.
The audience of your document may differ based on the type of document you’re writing. For instance, a technical document written for a programming audience can be different from a user guide written for an end user. Ditto for data sheets, press releases, product brochures or catalogues, white papers, or Web pages, to name a few. Therefore, it is crucial to give every document the precise review treatment it deserves, to have the maximum impact on your audience.
In order to achieve this, you should select a review process with a definitive workflow.
Defining the Workflow:
These days, most reviewers have to their disposal collaborative reviewing and editing tools, which enable them to perform mark up, place sticky notes, add or delete comments, and even attach other reference materials to the original or source document. This makes the authors’ life a tad easier while editing or making corrections to that document.
Figure: Document Creation and Review Workflow
You can decide how you want to send the documents for review: concurrently or sequentially. There are times when you need collaboration between reviewers. The reviewers may not have the appropriate tools to complete the review effectively, for example, they might not have access to tools that allow mark-up, annotations, or routing.
“An outstanding document can even make a mediocre product also look good.”
You have to arrange these tools for reviewers in that case. Delivering a quality document within a specific timeline is imperative. To achieve results, you have to include these aspects of the review process in your workflow.
Within the review process, you can also have the following aspects covered:
- Check the technical competency/ accuracy of the document
- Include useful information from test cases, exercises, and so on, in the document
- Check if all the features/ used cases are covered in the document
- Check for language review
- Making sure that the document meets “defined” standards, in terms of images, charts, templates, and the overall design element
Best Practices:
Many reviews are compromised due to missing or unavailable review resources or inadequate time. To avoid such handicaps, identify the reviewers, SMEs, engineering staff, and so on. Send the review plan to these people well in advance. This way, they could make a note on their calendar about the review dates.
- Introduce a topic-based review process
- Adopt an Agile Development Model in the review process (if possible)
- Identify/ envisage problems, determine ahead of time who’ll provide and review corrections and inform the reviewers when those efforts will substantiate
- Create a well thought out plan—one that optimizes the time spent by every individual, thus helping them to be as effective and efficient as possible
- Determine the benefits of each review and make use of critical information that can improvise the review process itself
- Collect all the key resources, for example, SMEs, reference documents, engineering documents, standard rules and templates, checklists (if any)
- Take the approval on the document design; an agreement in terms of what the document should contain
- Prepare (and provide) a defined process for planning and conducting reviews
“Delivering a quality document within a specific timeline is imperative. To achieve results, you have to include these aspects of the review process in your workflow.”
If you plan to have an internal review cycle, then you have to make sure that the reviewers know where to look, what to look for, time required, and so on, basically to optimize their efforts
Problem Areas:
The ultimate goal of an optimized review process is to determine product quality and to ensure that the product is ready for the next stage of development. These reviews depend on participation from the product development teams. However, it is my general observation that these reviews often leave out some important information. The reason is very simple; developers do not want to make themselves look bad finding problems that they should have already fixed. Hence, their participation is self‑relegated to simply answering questions. It is therefore very important that as a writer you ask the right questions.
Publishing your technical documents to a multi-channelled world is also important. Getting your documents translated into different languages could pose challenges at times. Probably, you will not have the time for checking the consistency, correctness, technicality of the document translated into a foreign language; especially during shorter timeframes.
There might be times when you get little review support from the development teams and almost no useful information about prior documents or reviews. With no access to engineering documents or no transfer of information at all, a review becomes highly improbable.
Sometimes, you simply do not have enough time to look deeply into the software. Your biggest fears might come to life in later stages of development when too many defects are found and schedules slip due to insufficient planning, debugging, fixing, and retesting.
To avoid such issues, you have to on a constant vigil all the time, by making sure you get all the desired information and related documents as early as possible. Also, install the product and test its features yourself. You have to test the product first, in order to write an effective and user-friendly document.
“It is my general observation that these reviews often leave out some important information. The reason is very simple; developers do not want to make themselves look bad finding problems that they should have already fixed. Hence, their participation is self‑relegated to simply answering questions. It is therefore very important that as a writer you ask the right questions.”
Conclusion:
There are many critical factors you may have to consider while defining your document review workflow. If you are writing different set of documents, it is critical that you select the right reviewers. At the end of the day, the most important criteria is not the bells and whistles the reviewers may have, but whether or not they can truly support your efforts and deliver based on your requirements and while doing so, provide a qualitative feedback.
Over the coming years, more and more information would take the form of online documentation. With the proliferation of online documentation, we’d have even better tools supporting the document review; enabling us to collaborate effectively in real time. As companies strive to bring products from concept to market faster to maintain their competitive advantage, they have to deliver good product documents, by being more efficient and effective with their review process.
Author: Girish Sharangpani, CEO and founder of The Knowledge Labs.
Girish is a proven technology practitioner with expertise in setting up IT incubation centres, offshore software development outfits, product marketing, business strategy and technical communications. He has over 25 years of experience; predominantly in the information technology space.
As a writer, Girish has co-authored technical and research papers on breast cancer, has created posters that were presented in international conferences, and has written patents, FDA, and regulatory and compliance documents. He has a graduate degree in advance accounting and auditing from The University of Pune, and a postgraduate certification in Computer Applications from the same university. You can contact the author here.
One Comment
Comments are closed.