From cc75e1d17b971a80f9677095bcb2909d5d044297 Mon Sep 17 00:00:00 2001 From: David Shevitz Date: Wed, 3 Mar 2021 00:05:34 +0000 Subject: [PATCH] docs: add contributors guide to aio (#41061) PR Close #41061 --- .pullapprove.yml | 9 ++++ .../guide/contributors-guide-overview.md | 39 +++++++++++++++++ aio/content/guide/reviewing-content.md | 40 ++++++++++++++++++ .../guide/updating-content-github-ui.md | 37 ++++++++++++++++ aio/content/guide/updating-search-keywords.md | 30 +++++++++++++ .../guide/contributors-guide/edit-icon.png | Bin 0 -> 416 bytes .../contributors-guide/last-reviewed.png | Bin 0 -> 3446 bytes aio/content/navigation.json | 21 +++++++++ 8 files changed, 176 insertions(+) create mode 100644 aio/content/guide/contributors-guide-overview.md create mode 100644 aio/content/guide/reviewing-content.md create mode 100644 aio/content/guide/updating-content-github-ui.md create mode 100644 aio/content/guide/updating-search-keywords.md create mode 100644 aio/content/images/guide/contributors-guide/edit-icon.png create mode 100644 aio/content/images/guide/contributors-guide/last-reviewed.png diff --git a/.pullapprove.yml b/.pullapprove.yml index 7f567ebf8a..f8a65a8fc0 100644 --- a/.pullapprove.yml +++ b/.pullapprove.yml @@ -1139,6 +1139,15 @@ groups: 'aio/src/**', 'aio/tests/**', 'aio/tools/**', + 'aio/content/images/guide/contributors-guide/**', + 'aio/content/guide/contributors-guide-overview.md', + 'aio/content/guide/contributors-guide-overview/**', + 'aio/content/guide/reviewing-content.md', + 'aio/content/guide/reviewing-content/**', + 'aio/content/guide/updating-content-github-ui.md', + 'aio/content/guide/updating-content-github-ui/**', + 'aio/content/guide/updating-search-keywords.md', + 'aio/content/guide/updating-search-keywords/**', 'aio/content/guide/docs-style-guide.md', 'aio/content/examples/docs-style-guide/**', 'aio/content/images/guide/docs-style-guide/**', diff --git a/aio/content/guide/contributors-guide-overview.md b/aio/content/guide/contributors-guide-overview.md new file mode 100644 index 0000000000..7d1b30065d --- /dev/null +++ b/aio/content/guide/contributors-guide-overview.md @@ -0,0 +1,39 @@ +# Content Contributor's Guide + +Angular, as an open source project, depends on its community. This dependence is particularly important to the documentation. The more the community contributes to the documentation, the better the documentation becomes, which helps both new and experienced Angular developers. + +The topics in this section cover ways in which you can contribute to the Angular documentation set. + +## Before you begin + +Before you get started with your contributions, we recommend that you review [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#contributing-to-angular). That topic explains many of the tasks and guidelines you need to know before you make your first pull request. + +## Contributing to Angular + +
+ +
Review content
+

Keep Angular content up-to-date by reviewing topics for accuracy.

+

Help keep content up to date

+ + +
Update search keywords
+

Help Angular developers by improving the search keywords for existing topics.

+

Improve documentation search

+ + +
Update content through GitHub
+

Learn how to make documentation changes through the GitHub UI.

+

Contribute to Angular in your browser

+ + +
Documentation style guide
+

Review the syntax and styles used within the Angular documentation set.

+

Get to know the writing style

+ +
+ diff --git a/aio/content/guide/reviewing-content.md b/aio/content/guide/reviewing-content.md new file mode 100644 index 0000000000..a842774f50 --- /dev/null +++ b/aio/content/guide/reviewing-content.md @@ -0,0 +1,40 @@ +# Reviewing content + +Angular developers work best when they have access to accurate and complete documentation. Keeping existing content up-to-date is an essential part of ensuring that all developers have a great documentation experience. + +This topic describes how you can help keep Angular content up-to-date by reviewing content. + +## Before you begin + +You can review content even if you've never contributed to Angular before. However, you may find it helpful to have the [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#contributing-to-angular) guide available if you're filing your first pull request in the repository. + +## Reviewing content (`@reviewed`) + +All of the task-based guides, tutorials, and conceptual topics that you find on Angular.io support a `@reviewed` tag. When present, this tag is followed by the date representing when a given topic was reviewed for accuracy and completeness. On the published topic, this reviewed information appears at the bottom of the topic; for example, `Last reviewed on` followed by the day of the week, month, day, and year. + +
+ Example of the last reviewed date specifying the day of the week, the month, the date, and the year on a page footer. +
+ +This reviewed date indicates when someone last reviewed the topic to ensure that its contents were accurate. + +You can review a topic using either the GitHub user interface or in an editor on your local machine. You can also review any topic that you like. Previous experience in the subject of the topic is helpful, but not required. + +**To review a topic:** + +1. Navigate to the topic that you want to review. + +1. Locate the last reviewed date at the bottom of the topic and verify that the topic meets the [review criteria](#review-criteria). + + If the topic does not have a last reviewed date, you are welcome to add it to the topic. + +1. Read through the topic. + +1. If the topic requires an update, either [file an issue](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-submitting-an-issue) that describes the update required, or [create a pull request](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-submitting-an-issue) with the update. + +1. Update the `@reviewed` tag, either through the [GitHub user interface](guide/updating-content-github-ui) or through Angular's [standard pull request process](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-submitting-an-issue). + +{@a review-criteria} +### Review criteria + +In general, topics should be reviewed either every six months, or around every major release. diff --git a/aio/content/guide/updating-content-github-ui.md b/aio/content/guide/updating-content-github-ui.md new file mode 100644 index 0000000000..0e0ec59552 --- /dev/null +++ b/aio/content/guide/updating-content-github-ui.md @@ -0,0 +1,37 @@ +# Updating topics through the GitHub user interface + +This topic describes how to submit pull requests to the Angular repository using GitHub's user interface. If you are unfamiliar with Git, you might find this process easier for making changes. + +
+ + Using the GitHub user interface for updates is recommended only for small changes, such as [updating the review date](guide/reviewing-content) or [updating search keywords](guide/updating-search-keywords). + +
+ +**To update a topic through the GitHub user interface:** + +1. Navigate to the topic for which you want to file a pull request. + +1. Click the edit icon at the top of the topic. + +
+ The edit icon for an Angular topic. +
+ + A GitHub page appears, displaying the source of the topic. + +1. Update the topic. + +1. At the bottom of the screen, update the Commit Changes box with a description of the change. Use the format `docs: `, where `` briefly describes your change. Keep the description under 100 characters. For example: + + `docs: fix typo in Tour of Heroes pt.1` + +1. Verify that the **create new branch** option is selected, then click **Commit Changes**. + + A Pull Request screen opens. + +1. Fill out the form in the Pull Request screen. At a minimum, put an `x` in the **Docs have been added / updated** option and the **Documentation content changes** option. + +1. Click **Create Pull Request**. + +At this point, your pull request is added to a list of current requests, which the documentation team reviews weekly. diff --git a/aio/content/guide/updating-search-keywords.md b/aio/content/guide/updating-search-keywords.md new file mode 100644 index 0000000000..121a857be5 --- /dev/null +++ b/aio/content/guide/updating-search-keywords.md @@ -0,0 +1,30 @@ +# Updating search keywords + +In documentation, being able to find the content you need is equally as important as the content itself. In Angular.io, users can discover content in several ways, including: + +* Organic search results, such as through google.com +* The table of contents, also known as the left navigation +* Using the search box on Angular.io + +You can help improve the documentation experience by adding search keywords to a given topic. Updating search keywords can help bring users to the content they need faster. + +## Before you begin + +You can update search keywords for a topic even if you've never contributed to Angular before. However, you may find it helpful to have the [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#contributing-to-angular) guide available if you're filing your first pull request in the repository. + +**To update search keywords:** + +1. Navigate to the topic to which you want to update search keywords. + +1. Decide what search keywords you'd like to add to the topic. For information on how to format keywords, see [Search keywords format](#format). + +1. Update the {`@searchKeywords tag`}, either through the [GitHub user interface](guide/updating-content-github-ui) or through Angular's [standard pull request process](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-submitting-an-issue). + + If a topic does not have a {`@searchKeywords`} tag, you can add it to the end of the topic. + +{@a format} +## Search keywords format + +You add search keywords to a topic using the {`@searchKeywords`} tag. This tag takes a set of single words, separated by spaces. For example: + +{`@searchKeywords route router routing navigation`} diff --git a/aio/content/images/guide/contributors-guide/edit-icon.png b/aio/content/images/guide/contributors-guide/edit-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..7124a1891428bcfa3193b0be0e54596d85b0e0dd GIT binary patch literal 416 zcmV;R0bl-!P)JbZrzX=ZmKOx(($Wzrp zKc2l{NSgVY;lK|@25oa$hBZO_Bs+?V4*JV*Y~5{!=##%0eu8}ta+Ey7njl`197Poe z{do3@q3t3kL$N12!|`SJ7&0$H9mONSu(?*2!I*@oqu4>n(PU&U&#*KI>ZqG63{~lh z45?DgBshnGfg%SX90RkHkpbc;4u((fm>Fb+m`HLAIHJj|?J*q#wVQ*Rp+8@VAzX-L zw?I-JIS#_@7*2*pGNK9D=_EUdmX0AgglO#;k{m=2#}MrxdO3zj2YqHJuYbU>_y=09 z;h;PLW6Otx6ZP*844E~L88#y8rjcWa3n6p|(a1Z)Uz8z$ z#Oi>QB9d^FkzyJZ)Q&ocP#}(m&}aw|3IRg$qiJX~gb0NIA$b5ko(`nP(pFdi0000< KMNUMnLSTaOAgVh6 literal 0 HcmV?d00001 diff --git a/aio/content/images/guide/contributors-guide/last-reviewed.png b/aio/content/images/guide/contributors-guide/last-reviewed.png new file mode 100644 index 0000000000000000000000000000000000000000..302ffabacf238f3aa5a1f24b71b101006df03890 GIT binary patch literal 3446 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