Documentation Review Process

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

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

    Documentation reviewers, maintainers, and WG leads follow a clear process to review content PRs to ensure all reviews are consistent. The process is as follows:

    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.

    Our review process supports our code of conduct by making our review criteria transparent and applying it to all content contributions.

    • Correct markup: All linting and tests pass.
    • Language: Content must be clear and understandable. To learn more see the highlights and 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.