Starting Wednesday, July 26th, the pull request reviewers will be checking all pull requests in azure-docs-pr that require human review for a minimum Acrolinx score prior to merge. After an initial run in azure-docs-pr, this requirement will be applied in all the repositories where the Aquent PR review team is working.
Here’s the details:
The starting minimum score is 80. This should be well within reach -- currently, only 20% of Azure conceptual content published to the https://docs.microsoft.com/en-us/azure path has an Acrolinx score below 80 (source: SkyEye Acrolinx report). Over time you can expect us to raise the bar higher.
Everyone should be making an effort to address the tone of voice and clarity feedback in Acrolinx reports – this feedback from Acrolinx is designed to make our content easier to understand and to give it a more conversational tone – directly aligned with Microsoft modern voice and with APEX’s customer focused review (CFR) efforts. We’re doing this for our customers’ benefit.
This does mean that you might have to fix pre-existing content that you didn’t intend to modify in a particular pull request. This is why we are starting with the bar at 80.
We use the term “false positive” to refer to cases where Acrolinx flags something as incorrect or needing a fix, but where you know that the usage is actually correct for the context. The minimum score is intended to accommodate for some false positives – there will always be some false positives we have to live with. It’s not possible or even desirable to add every term that generates a false positive to the system. You can request terms to be added when the terms are used broadly in a content set.
If lots of false positives in a pull request scorecard put the score of an article below 80 and cause your PR to be blocked, please take these steps:
- File a bug for the false positives using this link: https://aka.ms/acrolinxbug. Make sure you include a link to the PR, a link to the scorecard, and a clear description of why the flags are false positives.
- Contact azdocprs to let the PR reviewers know that one or more articles in the PR have a score lower than 80 due to false positives, and include a link to the Acrolinx bug. As long as you have filed an Acrolinx bug for the false positives, the PR reviewers can review the PR against all other criteria and merge as appropriate.
If you have been asked to make a high priority fix to an article to address a severe customer issue, or an executive, red zone, security, or privacy issue, you can request an exception to the score requirement if the issue is truly urgent and you cannot dedicate time to the fixes. Note that this is not about false positives – this is about not fixing valid Acrolinx flags. Carolz or tysonn need to approve the exemption. This will be handled on a case-by-case basis.
Requirements have been filed for PRmerger to add a business rule to bring automerging into alignment with this quality requirement.