Quality criteria for pull request edit review

These criteria are intended for authors who create and maintain technical articles, and for pull request reviewers who provide editorial review (not technical review) of pull request content quality.

If your pull request does not qualify for automatic merging, it will be reviewed by a human pull request reviewer for content quality. Pull request reviewers generally review only what is new or changed, according to the blocking and non-blocking quality review items listed in this article.

Blocking content quality items

The updates in the pull request must comply with the following criteria to be merged. Pull request reviewers provide feedback in pull request comments for these items and type #hold-off in the pull request to return it to you (the author) with feedback.

Category Quality review item
Prerequisites The "ready-to-merge" label is assigned to the PR (use the #sign-off comment) and the validation status is "passed".
Prerequisites Any pull request to the Live branch should be closed. The user should be redirected to the master branch.
Prerequisites The pull request cannot be blocked by a merge conflict. If there is a merge conflict, refer the user to https://github.com/blog/2293-resolve-simple-merge-conflicts-on-github for instructions on how to use the GitHub UI to resolve merge conflicts. PR reviewers do not resolve conflicts.
Prerequisites The sign-off comment must appear after the validation results and staging links - if it appears before the staging links, it means the author did not review the staged content.
Prerequisites All articles in the pull request must have an Acrolinx score of 80 or higher (where Acrolinx enabled in the PR queue). Limited exceptions are available.
Repo integrity Pull request contains no obvious content regressions.
Repo integrity No article-related files, images, or folders are being added to the root directory of the repo.
Repo integrity Pull requests that change a configuration file in the root folder must be reviewed and merged by the repo administrator.
Repo integrity Pull request does not include an embedded repo or any unusual, extraneous files. All file updates should be restricted to the articles and includes folders in the repo. Items to watch for: .DS_Store, desktop.ini, .gitignore, azure-docs-pr embedded in root folder.
Repo integrity Pull request contains fewer than 100 changed files unless the PR intentionally is updating a release branch from master. (Really, a PR should contain far fewer than that, but after 100 changed files, GitHub doesn’t display the diffs).
Repo integrity If articles are deleted in the pull request, the deletions must be by the listed author. Where PRMerger is running, authors who are deleting articles must list themselves as the author in a commit that precedes the commit to delete the articles to avoid a validation warning. This ensures that deletions are intentional
Repo integrity All deleted articles are accompanied by an entry in the master redirect file to an appropriate new target. If the repo uses a master redirect file, redirects use only the master redirect method. File-based redirects are not allowed in repos that use master file redirection.
Naming File names for new files follow the file naming guidelines.
Naming New folders introduced into the repo follow the folder naming guidelines.
Metadata A metadata section is present at the top of the file. The metadata section starts with three hyphens, is followed by a list of metadata that includes at a minimum title, author, ms.author, ms.date, ms.topic, and ms.service OR ms.technology, and ends with three hyphens. In Azure, the service value is also required.
Metadata The ms.date value cannot be set more than 5 days into the future.
Content The article is a technical document, and therefore in the correct content channel. See the what goes where guidance.
Content The subject matter in the technical document is appropriate for a technical article. See the what goes where guidance.
Content Bylines are not permitted; if an article calls out the name of the author or any contributor in the text, that attribution needs to be removed. Articles published from the tech content repo are considered to be authored by "Microsoft". Contributors who have committed updates to the article are recognized automatically on the contributor bar of the published article.
Content The article contains only one H1 heading.
Content The article contains an introductory paragraph, and a procedural or conceptual body of content. The article needs to contain sufficient, complete content to stand on its own as an article. It should not be a small fragment of information. (Exception: A "Limits" topic if it is in the context of a large article that lists all of the limits of a service.)
Content Elements that should be numbered lists are numbered, elements that should be unordered lists are bulleted. This is basic usability.
Content Unusual or novel graphics, information architecture or structures, or obviously non-standard designs need to be vetted with the lead PR reviewer. Teams that are experimenting with new things need to have a problem/solution canvas or plan in place for evaluating experiments.
Content If an article is being deleted, all crosslinks to that article must be deleted. Check the build report to ensure there are no articles that contain broken links to the article being deleted
Site/design functionality Switchers are used only for switching across multiple versions of the same article.
Site/design functionality Tabs in conceptual (aka: tabbed conceptual) content is a new OPS feature not authorized for broad usage at this time in C+E technical content. Only authorized pilot content should use the tabs feature. Any PR that contains conceptual tabs needs to be approved by Carolz, no exceptions. See the draft guidelines.
Site/design functionality The titles of switchered articles contain information that differentiates each article from the other articles in the switchered set.
Site/design functionality Manually authored TOCs are not permitted. The article must rely on H2s for its on-page TOC.
Site/design functionality If H2 headings are present, the article contains at least two H2 headings. Using one H2 heading creates a single-item article TOC. H2 headings must be used before H3 headings to ensure a TOC is created.
Site/design functionality When a new article is added, the TOC is updated at the same time.
Markdown HTML: Source content does not contain HTML at the block level – minor inline HTML is permitted – such as superscript, subscript, special characters, and other minor things that you can’t do with markdown. HTML tables are allowed ONLY if the table contains bulleted or numbered lists, but that is usually an indication the content needs to be simplified so the source can be coded in markdown.
Markdown Custom markdown elements are used where appropriate. Ex: Notes are coded using the [!NOTE] extension, not as plain text.
SEO The title metadata value must include a branded product name. In Azure content, the title must contain the word "Azure" (Intune, Operations Management Suite [OMS], StorSimple, and Cognitive Services articles are excepted). In other repositories, ensure a product name is present.
SEO The H1 title contains sufficient information to describe the content of the article, to differentiate it from other articles in our content set, and to map to likely customer keywords. For example "Overview" as the H1 title is completely generic and provides no useful information to a customer or to search.
Terminology The use of the ARM acronym, V1, or V2 as references to the classic and Resource Manager deployment models in Azure is a blocking terminology item.
Images Animated GIFs and PDN files are not accepted into the repo.
Images Images have clear resolution, are free of misspelled words, and contain no private information
Localizability Links to pages on azure.microsoft.com, TechNet, and MSDN are coded as locale agnostic. Do not include en-us, en-gb, en-in, or any other locale in links to these sites. TechNet/MSDN forum links are an exception - locales cannot be removed from forum links on these sites.
Staging The article preview must be clean on staging. It cannot contain any obvious formatting issues:
- A numbered or bulleted list that appears as a paragraph
- Code in a code block appearing partly in the code block and partly outside it
- Numbered steps numbered incorrectly due to faulty indentation
- Leftover merge conflict markers

Non-blocking content quality items

For these items, pull request reviewers provide feedback and instructions for the author to follow up with fixes in a later pull request. However, this feedback does not block the decision to merge. Authors should follow up within 3 business days with fixes.

Category Quality review item
Content Articles should have a “Next steps” at the end with 1-3 relevant and compelling next steps. Brief text should be included that helps the customer understand why the next steps are relevant. (New articles only). Example: https://docs.microsoft.com/cli/azure/install-azure-cli
Content Spelling, grammar, and other writing issues - pull request reviewers may provide feedback on a few minor issues as non-blocking feedback. If there are more than a few editorial issues, reviewers log an edit request for the article for a post-publication edit.
Images Images use the correct callout style and color, and screenshots use the correct border and placeholder style. See the image guidance.
Images Images include alt text. See the image guidance.
Site/design functionality The H2 headings, when rendered in the on-page TOC, should ideally wrap to no more than 2 lines. Longer headings make the article TOC harder to scan.
Style conventions All titles and headings are sentence case, per Azure style.
Process If the pull request could have easily been reconfigured to benefit from PRmerger automation, pull request reviewers provide feedback to the author about how to use branches so the changes could be merged automatically. See the PR etiquette article.