Part 1 of 2: publicize docs fundamentals, simplify self-review checkl… · github/docs@f07eebb · GitHub
Skip to content

Commit f07eebb

Browse files
jc-clarkethanpalmHector Alfarosubatoiheiskr
authored
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>
1 parent 40bbab6 commit f07eebb

9 files changed

Lines changed: 46 additions & 88 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 4 additions & 5 deletions

‎.github/review-template.md‎

Lines changed: 0 additions & 36 deletions
This file was deleted.

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

Lines changed: 0 additions & 39 deletions
This file was deleted.

‎.github/workflows/comment-release-note-info.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525
with:
2626
issue-number: ${{ github.event.pull_request.number }}
2727
body: |
28-
Thank you for updating our GitHub Enterprise Server release notes. A member of the `docs-content-enterprise` team will review your changes.
28+
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.
2929
3030
- If the change is urgent, post in `#docs-content-enterprise` on Slack.
3131
- 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‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,11 +44,11 @@ jobs:
4444
- name: Comment on the PR
4545
if: steps.membership_check.outputs.result == 'false'
4646
run: |
47-
gh pr comment $PR --body "Thanks so much for opening this PR and contributing to GitHub Docs!
47+
gh pr comment $PR --body "### Next: add the review label
4848
49-
- 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.**
50-
- If you're adding a release note, request a technical review. The Docs team will review the PR after the technical review is complete.
51-
- 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."
49+
**🛎️ Is this PR ready for review?** A PR is ready for a docs review _after_ the self-review checklist is complete.
50+
51+
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._
5252
5353
env:
5454
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎content/contributing/collaborating-on-github-docs/self-review-checklist.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ Before you submit your changes to the {% data variables.product.prodname_docs %}
99

1010
* Changes meet the **content goals and user needs** in the content design plan, if one has been created.
1111
* Content has been **confirmed for accuracy** by a subject matter expert (SME) in the technical area.
12-
* 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)."
13-
* Content is **free of errors** such as typos and adheres to the "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)."
12+
* 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)."
1413
* The article **renders properly on staging** for each version of the article (Free Pro Team, GHEC, GHES).
1514
* All **pull request checks** are passing.
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: About GitHub's documentation fundamentals
3+
shortTitle: Documentation fundamentals
4+
intro: 'All content published on {% data variables.product.prodname_docs %} must meet these fundamental requirements.'
5+
versions:
6+
feature: 'contributing'
7+
---
8+
9+
## About {% data variables.product.github %}'s documentation fundamentals
10+
11+
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.
12+
13+
## Accurate
14+
15+
Documentation is correct and accurate.
16+
17+
* Ensure that the content is free from factual errors.
18+
* Ensure that the content is free from spelling and formatting errors.
19+
20+
## Accessible and inclusive
21+
22+
Documentation is up to date with the latest accessibility standards, and is written to be inclusive and translation-friendly.
23+
24+
* Ensure content adheres to the accessibility and screenshot guidelines. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/creating-screenshots)."
25+
* Ensure content can be successfully translated. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated)."
26+
27+
## Consistent
28+
29+
Documentation maintains a consistent voice, tone, and style throughout, creating a cohesive experience for readers.
30+
31+
* 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)."
32+
* Apply consistent terminology and naming conventions.
33+
* 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‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,10 @@ versions:
1010

1111
At {% data variables.product.prodname_dotcom %}, we strive to create documentation that is accurate, valuable, inclusive, accessible, and easy to use.
1212

13-
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:
13+
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:
1414

1515
* [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)
16+
* [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)
1617
* [AUTOTITLE](/contributing/writing-for-github-docs/content-design-principles)
1718

1819
## Best practices for writing {% data variables.product.prodname_dotcom %} documentation

‎content/contributing/writing-for-github-docs/index.md‎

Lines changed: 1 addition & 0 deletions

0 commit comments

Comments
 (0)