These criteria are intended for authors who create and maintain technical articles and for pull request reviewers who review content pull requests. If your pull request does not qualify for automatic merging, it will be reviewed by a human pull request reviewer. Pull request reviewers generally review only what is new or changed. Pull request reviewers evaluate the changes in a pull request according to the blocking and non-blocking quality review items listed in this article.
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 pull request contains updates only to technical articles and images. PRs that mix updates to TOC files, index files, and articles will be closed without further review. |
| 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. If not by the listed author, the PR must contain a comment indicating the article deletions are intentional |
| Naming | File names for new files follow the file naming guidelines. |
| Naming | New folders introduced into the repo follow the folder naming guidelines. |
| Metadata | Metadata section is in the correct YAML format for OPS. |
| 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 | 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 | If articles are added or deleted, the author needs to link to the PR that includes the appropriate TOC changes. If the author has not coordinated for TOC changes for a new or removed article, they should open a bug at https//aka.ms/azuretodocsbug and hold off on changes until the TOC is ready. |
| 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 " | Microsoft Docs" site identifier is required. We no longer use the " | Microsoft Azure" site identifier |
| SEO | The title metadata value must include the word "Azure" (Operations Management Suite articles are excepted) |
| SEO | The H1 title contains sufficient information to describe the content of the article, to differentiate it from other Azure articles, and to map to likely customer keywords. For example "Overview" as the H1 title is a fail. |
| Terminology | The use of the ARM acronym, V1, or V2 as references to the classic and Resource Manager deployment models 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. |
| 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 |
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/en-us/documentation/articles/xplat-cli-install/ |
| 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. |
| Process | When you delete or rename an article, make sure you follow the process. Pull request reviewers should add the following comment and link in a comment: Please verify you followed the process in the contributors’ guide for deleting articles: https://github.com/Azure/azure-docs-pr/blob/master/contributor-guide/retire-or-rename-an-article.md |