Documentation Review Process

    A documentation reviewer is a trusted contributor that approves content that meets the acceptance criteria described in the . All content reviews follow the process described in Reviewing content PRs.

    Only Docs Maintainers and WG Leads can merge content into the .

    Content for Istio often needs to be reviewed on short notice and not all content has the same relevance. The last minute nature of contributions and the finite number of reviewers make the prioritization of content reviews necessary to function at scale. This page provides clear review criteria to ensure all review work happens consistently, reliably and follows the same quality standards.

    1. The Contributor submits a new content PR to the istio.io repository.
    2. The Reviewer performs a review of the content and determines if it meets the acceptance criteria.
    3. The Reviewer adds any technical WG pertinent for the content if the contributor hasn’t already.
    4. The Contributor and the Reviewer work together until the content meets all required acceptance criteria and the issues are addressed.
    5. If the content is urgent and meeting the supplemental acceptance criteria requires significant effort, the Reviewer files a follow up issue on the istio.io repository to address the problems at a later date.
    6. When a technical WG lead or maintainer approves the content PR, the Reviewer can approve the PR.
    7. If a Docs WG maintainer or lead reviewed the content, they not only approve, but they also merge the content. Otherwise, maintainers and leads are automatically notified of the Reviewer’s approval and prioritize approving and merging the already reviewed content.

    The following diagram depicts the process:

    • Contributors perform the steps in the gray shapes.
    • Reviewers perform the steps in the blue shapes.
    • Docs Maintainers and WG Leads perform the steps in the green shapes.

    When a Reviewer files a follow up issue as part of the , the GitHub issue must include the following information:

    • Details about the supplemental acceptance criteria the content failed to meet.
    • Link to the original PR.
    • Username of the technical Subject Matter Experts (SMEs).
    • Labels to sort the issues.
    • Estimate of work: Reviewers provide their best estimate of how long it would take to address the remaining issues working alongside the original contributor.

    Criteria has two tiers: required and supplemental.

    • Correct markup: All linting and tests pass.
    • Language: Content must be clear and understandable. To learn more see the and general principles of the Google developer style guide.
    • Links and navigation: The content has no broken links and the site builds properly.

    Supplemental acceptance criteria

    • Content structure: Information structure enhances the readers’ experience.
    • Consistency: Content adheres to all recommendations in the
    • Style: Content adheres to the Google developer style guide.

    • Graphic assets: Diagrams follow the Istio .

    • Code samples: Content provides relevant, testable, and working code samples.

    • Content reuse: Any repeatable content follows a reusability strategy using boilerplate text.
    • Glossary: New terms are added to the glossary with clear definitions.