Part 1 of 2: publicize docs fundamentals, simplify self-review checklist and pull request template (#52624)

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: Hector Alfaro <hectorsector@github.com>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>

.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:
 
 <!-- If there's an existing issue for your change, please link to it above.
 If there's _not_ an existing issue, please open one first to make it more likely that this update will be accepted: https://github.com/github/docs/issues/new/choose. -->
@@ -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).
+- [ ] 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).
-  - 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.
+- [ ] All CI checks are passing.
-- [ ] For content changes, I have completed the [self-review checklist](https://docs.github.com/en/contributing/collaborating-on-github-docs/self-review-checklist).

.github/review-template.md

@@ -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._

.github/workflows/add-review-template.yml

@@ -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<<EOF" >> $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 }}

.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).

.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.**
+          **🛎️ Is this PR ready for review?** A PR is ready for a docs review _after_ the self-review checklist is complete.
-          - 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."
+           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 }}

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 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)."
-* Content is **free of errors** such as typos and adheres to the "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)."
 * The article **renders properly on staging** for each version of the article (Free Pro Team, GHEC, GHES).
 * All **pull request checks** are passing.

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.

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

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