Systematic checking of the safety manual pages with Hemingway and Grammarly

While the documentation pages are in very good shape, it is possible to tweak them further by using some modern tools. This will provide a relief for the reviews, when the automated checks have been run first. Early detection of possible typing errors enables reviewers to fully focus on the actual content of the pages.

One time effort for going through the existing documentation:

1) Public online documentation

The recommended pair of tools is the use of the hemingwayapp.com page in the Chrome browser with the Grammarly plugin enabled.  

• Copy & paste each online document page content into the hemingwayapp and let those two tools do the checking.
  • Suppress warnings that are not relevant for this, for example use of the passive
• Check each finding by the Grammarly tool and determine if it is valid point or false positive. Fix those that are deemed valid.
• After fixing the Grammarly findings and suppressing the false-positives, pay attention to the Hemingway tool findings. 
  • Consider improving the readability index, so that it would be suitable for the global use. Not all people who read the documentation are native English speakers, so try to simplify it enough.
• After checking the page, apply the changes to the corresponding source code files.
• Process each page.

2) Private unit test documentation

Do the same kind of processing for these HTML pages.

Recurring efforts for the new documentation changes

For each new change regarding the documentation we can do the same checking to avoid any regression in the quality of the documentation. This can be done for the small code snippets when modifying the existing documentation due to the feature development or other maintenance work. Or when adding new pages when developing new release.

?

Oh why? The Qt product marketing has proven these tools to be useful in checking the material that will be published. We could easily do the same for our deliverables.