Quality criteria for pull request edit review

These criteria are 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, a human pull request reviewer will review it 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 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 The 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 The 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 the root folder.
Repo integrity The pull request contains fewer than 100 changed files, unless the PR is intentionally 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.prod, and ends with three hyphens. In Azure, the services value is also required.
Metadata The ms.date value cannot be set more than five days in the future.
Content The article is a technical document and therefore is 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 TOC files: when a new article is added, the TOC must be updated at the same time.
Content If an index page is modified, review and sign-off by a designated business approver is required. Minor fixes on landing pages such as spelling fixes and link correction or replacement do not need approval. Addition of any new content does require approval.
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. (An exception is a "Limits" topic if it's 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 nonstandard 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 that 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 (also known as "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 pull request that contains conceptual tabs needs to be approved by erifkin--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 that a TOC is created.
Markdown 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 that the content needs to be simplified so the source can be coded in Markdown.
Markdown Custom Markdown elements are used where appropriate. For example, notes are coded through 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 that a product name is present. A branded product name in the titleSuffix metadata value also meets this requirement.
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, or the use of V1 or V2 as a reference to the classic and Resource Manager deployment models in Azure, is a blocking terminology item.
Images Animated GIFs and PDN files are not accepted in 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 three business days with fixes.

Category Quality review item
Content Articles should have a “Next steps” section at the end with one to three relevant and compelling next steps. Brief text should be included that helps the customer understand why the next steps are relevant. (This rule is for new articles only.) For example:
Example "Next steps" section
Content Pull request reviewers might provide feedback on a few minor spelling, grammar, and other writing 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 two 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 can be merged automatically. See the PR etiquette article.

PRs that require repository admin review and merge

  • Configuration file updates
  • PRs that involve more than 100 files