diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0195011ff9..c930eff3a2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,7 +4,7 @@ Thank you for contributing to this project! You must fill out the information be ### Why: -Closes: +Closes: @@ -16,7 +16,6 @@ If you made changes to the `content` directory, a table will populate in a comme ### Check off the following: -- [ ] I have reviewed my changes in staging, available via the **View deployment** link in this PR's timeline (this link will be available after opening the PR). - - - For content changes, you will also see an automatically generated comment with links directly to pages you've modified. The comment won't appear if your PR only edits files in the `data` directory. -- [ ] For content changes, I have completed the [self-review checklist](https://docs.github.com/en/contributing/collaborating-on-github-docs/self-review-checklist). +- [ ] A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. In most cases, the author can be the SME. Open source contributions may require a SME review from GitHub staff. +- [ ] The changes in this PR meet [the docs fundamentals that are required for all content](http://docs.github.com/en/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals). +- [ ] All CI checks are passing. diff --git a/.github/review-template.md b/.github/review-template.md deleted file mode 100644 index 6aeb6e69d7..0000000000 --- a/.github/review-template.md +++ /dev/null @@ -1,36 +0,0 @@ -## Author self-review - -- [ ] The changes in this PR meet the user experience and goals outlined in the content design plan. -- [ ] The changes in this PR adhere to our [style guide](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide), [content model](https://docs.github.com/en/contributing/writing-for-github-docs/content-model), and "[Writing content to be translated](https://docs.github.com/en/contributing/writing-for-github-docs/writing-content-to-be-translated)." -- [ ] Compare this PR's source changes to the preview deployment and review for versioning issues, redirects, rendering problems, typos, and wonky screenshots. -- [ ] All screenshots in this PR adhere to the guidance in "[Creating screenshots](https://docs.github.com/en/contributing/writing-for-github-docs/creating-screenshots)." -- [ ] All checks are passing. -- [ ] For REST API content, verify that endpoints, parameters, and responses are correct and work as expected and provided curl samples below. - -For more information, check out our [review process](https://github.com/github/docs-team/blob/main/contributing-to-docs/review-process.md). - -## Review request - -### Summary - -_Help reviewers understand this project and its context by writing a paragraph summarizing its goals and intended user experience and explaining how the PR meets those goals._ -[Content design plan](LINK HERE) - -### Docs Content review - -_Give Docs Content any extra context, highlight areas for them to consider in their review, and ask them questions you need answered to ship the PR._ - -### Technical review - -_Ping in technical reviewers, asking them to review whether content is technically accurate and right for the audience._ -_Highlight areas for them to consider in their review and ask them questions you need answered to ship the PR._ - -### Content changes - -[PR on staging](LINK HERE) - -_Give a high-level overview of the changes in your PR and how they support the overall goals of the PR. Share links to important articles or changes in source and on staging. If your PR is large or complex, use a table to highlight changes with high user impact._ - -### Notes - -_Discuss test failures, versioning issues, or anything else reviewers should know to consider the overall user experience of the PR._ diff --git a/.github/workflows/add-review-template.yml b/.github/workflows/add-review-template.yml deleted file mode 100644 index c3490a1919..0000000000 --- a/.github/workflows/add-review-template.yml +++ /dev/null @@ -1,39 +0,0 @@ -name: Add review template - -# **What it does**: When a specific label is added to a PR, adds the contents of .github/review-template.md as a comment in the PR -# **Why we have it**: To help Docs Content team members ensure that their PR is ready for review -# **Who does it impact**: docs-internal maintainers and contributors - -on: - pull_request: - types: - - labeled - -permissions: - contents: read - -jobs: - comment-that-approved: - name: Add review template - runs-on: ubuntu-latest - if: github.event.label.name == 'add-review-template' && github.repository == 'github/docs-internal' - - steps: - - name: Checkout - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 - - # Jump through some hoops to work with a multi-line file - - name: Store review template in variable - run: | - TEMPLATE=$(cat .github/review-template.md) - echo "TEMPLATE<> $GITHUB_ENV - echo "$TEMPLATE" >> $GITHUB_ENV - echo "EOF" >> $GITHUB_ENV - - - name: Comment on the PR - run: | - gh pr comment $PR --body "$TEMPLATE" - env: - GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_WORKFLOW_READORG }} - PR: ${{ github.event.pull_request.html_url }} - TEMPLATE: ${{ env.TEMPLATE }} diff --git a/.github/workflows/comment-release-note-info.yml b/.github/workflows/comment-release-note-info.yml index d1b6e4059a..e34eacd0f3 100644 --- a/.github/workflows/comment-release-note-info.yml +++ b/.github/workflows/comment-release-note-info.yml @@ -25,7 +25,7 @@ jobs: with: issue-number: ${{ github.event.pull_request.number }} body: | - Thank you for updating our GitHub Enterprise Server release notes. A member of the `docs-content-enterprise` team will review your changes. + Thank you for updating our GitHub Enterprise Server release notes. Please request a technical review for your changes. Once the technical review is complete, a member of the `docs-content-enterprise` team will review your changes. - If the change is urgent, post in `#docs-content-enterprise` on Slack. - Review the [style guide for release notes](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#release-notes). diff --git a/.github/workflows/hubber-contribution-help.yml b/.github/workflows/hubber-contribution-help.yml index ed876e6295..0df92207b0 100644 --- a/.github/workflows/hubber-contribution-help.yml +++ b/.github/workflows/hubber-contribution-help.yml @@ -44,11 +44,11 @@ jobs: - name: Comment on the PR if: steps.membership_check.outputs.result == 'false' run: | - gh pr comment $PR --body "Thanks so much for opening this PR and contributing to GitHub Docs! + gh pr comment $PR --body "### Next: add the review label - - When you're ready for the Docs team to review this PR, add the *ready-for-doc-review* label to your PR, and it will be automatically added to the [Docs Content review board](https://github.com/orgs/github/memexes/901?layout=table&groupedBy%5BcolumnId%5D=11024). **Please factor in at least 72 hours for a review, even longer if this is a substantial change.** - - If you're adding a release note, request a technical review. The Docs team will review the PR after the technical review is complete. - - If your updates to the docs are more than a simple fix, you might want to go back and open an [issue](https://github.com/github/docs-content/issues/new/choose) to ensure we've covered all areas of the docs in these updates. Not doing so may result in delays or inaccurate documentation." + **🛎️ Is this PR ready for review?** A PR is ready for a docs review _after_ the self-review checklist is complete. + + When this is ready for review, add the **\`ready-for-doc-review\`** label to this PR. The PR will then be automatically added to the [Docs Content review board](https://github.com/orgs/github/projects/2936). _Please allow at least 3 working days for a review, and longer if this is a substantial change._ env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/content/contributing/collaborating-on-github-docs/self-review-checklist.md b/content/contributing/collaborating-on-github-docs/self-review-checklist.md index 1704462f40..595daf78a9 100644 --- a/content/contributing/collaborating-on-github-docs/self-review-checklist.md +++ b/content/contributing/collaborating-on-github-docs/self-review-checklist.md @@ -9,7 +9,6 @@ Before you submit your changes to the {% data variables.product.prodname_docs %} * Changes meet the **content goals and user needs** in the content design plan, if one has been created. * Content has been **confirmed for accuracy** by a subject matter expert (SME) in the technical area. -* Content follows **quality guidelines** in "[AUTOTITLE](/contributing/writing-for-github-docs/best-practices-for-github-docs)" and "[AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated)." -* Content is **free of errors** such as typos and adheres to the "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)." +* Content satisfies {% data variables.product.github %}'s **documentation fundamentals** that are required for all content. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)." * The article **renders properly on staging** for each version of the article (Free Pro Team, GHEC, GHES). * All **pull request checks** are passing. diff --git a/content/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals.md b/content/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals.md new file mode 100644 index 0000000000..7aa2bd7d4d --- /dev/null +++ b/content/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals.md @@ -0,0 +1,33 @@ +--- +title: About GitHub's documentation fundamentals +shortTitle: Documentation fundamentals +intro: 'All content published on {% data variables.product.prodname_docs %} must meet these fundamental requirements.' +versions: + feature: 'contributing' +--- + +## About {% data variables.product.github %}'s documentation fundamentals + +These fundamentals are required for {% data variables.product.github %} documentation. Use the lists below to help ensure your contributions are accurate, accessible and inclusive, and consistent. + +## Accurate + +Documentation is correct and accurate. + +* Ensure that the content is free from factual errors. +* Ensure that the content is free from spelling and formatting errors. + +## Accessible and inclusive + +Documentation is up to date with the latest accessibility standards, and is written to be inclusive and translation-friendly. + +* Ensure content adheres to the accessibility and screenshot guidelines. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/creating-screenshots)." +* Ensure content can be successfully translated. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated)." + +## Consistent + +Documentation maintains a consistent voice, tone, and style throughout, creating a cohesive experience for readers. + +* Ensure content adheres to the {% data variables.product.prodname_docs %} style guide. For more information, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)." +* Apply consistent terminology and naming conventions. +* Use branding elements (for example, product and feature names, logos, color schemes) consistently in the content. diff --git a/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md b/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md index 32692ed5ee..2435f3a5da 100644 --- a/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md +++ b/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md @@ -10,9 +10,10 @@ versions: At {% data variables.product.prodname_dotcom %}, we strive to create documentation that is accurate, valuable, inclusive, accessible, and easy to use. -Before contributing to {% data variables.product.prodname_docs %}, please take a moment to familiarize yourself with {% data variables.product.prodname_dotcom %}'s documentation philosophy and content design principles: +Before contributing to {% data variables.product.prodname_docs %}, please take a moment to familiarize yourself with {% data variables.product.prodname_dotcom %}'s documentation philosophy, fundamentals, and content design principles: * [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy) +* [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals) * [AUTOTITLE](/contributing/writing-for-github-docs/content-design-principles) ## Best practices for writing {% data variables.product.prodname_dotcom %} documentation diff --git a/content/contributing/writing-for-github-docs/index.md b/content/contributing/writing-for-github-docs/index.md index e2c648ea2e..235a8f8cc9 100644 --- a/content/contributing/writing-for-github-docs/index.md +++ b/content/contributing/writing-for-github-docs/index.md @@ -7,6 +7,7 @@ versions: children: - /best-practices-for-github-docs - /about-githubs-documentation-philosophy + - /about-githubs-documentation-fundamentals - /content-design-principles - /writing-content-to-be-translated - /making-content-findable-in-search