Skip to content

Commit 32831be

Browse files
author
Bob Watson
committed
docs: set titles to sentence case
* update overview and reviewing topics to accommodate new ToC * incorporate edits from peer reviews
1 parent 422323c commit 32831be

File tree

4 files changed

+305
-198
lines changed

4 files changed

+305
-198
lines changed

‎aio/content/guide/contributors-guide-overview.md‎

Lines changed: 101 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,85 @@
1-
# Documentation contributor's guide
1+
# Documentation contributor guide
22

3-
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.
3+
The topics in this section describe how you can contribute to this documentation.
4+
For information about contributing only code to the Angular framework, see [Contributing to Angular][GithubAngularAngularBlobMainContributingMd].
45

5-
The topics in this section cover ways in which you can contribute to the Angular documentation set.
6+
Angular, an open source project, depends on its community, especially when it comes to the documentation.
7+
The more the community contributes to the documentation, the better the documentation becomes.
8+
Input from you helps both new and experienced Angular developers.
69

7-
## Before you begin
10+
<div class="alert is-important">
811

9-
Before you get started with your contributions, review [Contributing to Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md). That topic explains many of the tasks and guidelines you need to know before you make your first pull request.
12+
You must have a GitHub account to propose a minor change or review and edit the documentation.
1013

11-
## Contributing to Angular documentation
14+
</div>
15+
16+
## Propose a minor change
17+
18+
You can propose minor changes to a documentation topic without downloading any software. Choose the pencil icon&nbsp;<img alt="drawing of a pencil used as the topic edit icon" src="generated/images/guide/contributors-guide/edit-icon.png" > at the top of the page, to the right of the topic title to enter your suggestion.
19+
20+
## Review and edit documentation topics
21+
22+
This section describes how to make larger contributions to the documentation.
23+
24+
### Before you start
25+
26+
The following steps set up your local computer to contribute documentation content.
27+
28+
1. Sign into your account on GitHub.
29+
If you don't have an account on GitHub, [create a new account][GithubJoin] before you continue.
30+
2. In your browser, navigate to [https://github.com/angular/angular][GithubAngular].
31+
3. In your browser, fork the `angular/angular` repo into your GitHub account.
32+
1. From [https://github.com/angular/angular][GithubAngular] in the browser, choose the **Fork** button near the top-right corner of the page.
33+
2. If asked, choose to create a fork to contribute to the original project.
34+
4. On the computer that you want to edit, clone your fork of the `angular` repo.
35+
5. In the `angular/aio` directory of your cloned repo, locally build and view the documentation.
36+
1. Run the following commands.
37+
To learn more, see [Angular documentation project][GithubAngularAngularBlobMainAioReadmeMd].
38+
39+
<code-example format="shell" language="shell">
40+
41+
yarn
42+
43+
</code-example>
44+
45+
<code-example format="shell" language="shell">
46+
47+
yarn setup
48+
49+
</code-example>
50+
51+
<code-example format="shell" language="shell">
52+
53+
yarn build
54+
55+
</code-example>
56+
57+
<code-example format="shell" language="shell">
58+
59+
yarn start
60+
61+
</code-example>
62+
63+
<div class="callout is-helpful">
64+
65+
**NOTE**: <br/>
66+
If you have any errors or issues with your yarn install, just re-run the `yarn` command.
67+
68+
</div>
69+
70+
2. In your browser, navigate to [http://localhost:4200][AngularLocalhost]
71+
3. Review your local build of the Angular framework documentation.
72+
73+
After you can see your local build of the Angular framework documentation on your own system, you are ready to review and edit it. The following sections help you with the next steps.
74+
75+
### Before you edit the documentation
76+
77+
The following steps prepare you to edit the Angular documentation successfully:
78+
79+
1. Review [Contributing to Angular][GithubAngularAngularBlobMainContributingMd].
80+
2. Install [the documentation linter][GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd].
81+
82+
### Ways to contribute to Angular documentation
1283

1384
<div class="card-container">
1485
<a href="guide/reviewing-content" class="docs-card" title="Reviewing content">
@@ -26,6 +97,11 @@ Before you get started with your contributions, review [Contributing to Angular]
2697
<p>Learn how to make documentation changes through the GitHub UI.</p>
2798
<p class="card-footer">Contribute to Angular in your browser</p>
2899
</a>
100+
</div>
101+
102+
### More resources for contributing to documentation
103+
104+
<div class="card-container">
29105
<a href="guide/docs-style-guide" class="docs-card" title="Documentation Style Guide">
30106
<section>Documentation style guide</section>
31107
<p>Review the syntax and styles used within the Angular documentation set.</p>
@@ -38,3 +114,22 @@ Before you get started with your contributions, review [Contributing to Angular]
38114
</a>
39115
</div>
40116

117+
<!-- links -->
118+
119+
<!-- external links -->
120+
121+
[GithubJoin]: https://github.com/join "Join GitHub | GitHub"
122+
123+
[GithubAngular]: https://github.com/angular/angular "angular/angular | GitHub"
124+
125+
[GithubAngularAngularBlobMainAioReadmeMd]: https://github.com/angular/angular/blob/main/aio/README.md "Angular documentation project (https://angular.io) | angular/angular | Github"
126+
127+
[GithubAngularAngularBlobMainContributingMd]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md "Contributing to Angular | angular/angular | Github"
128+
129+
[GithubAngularAngularTreeMainAioToolsDocLinterInstallValeOnYourDevelopmentSystemReadmeMd]: https://github.com/angular/angular/tree/main/aio/tools/doc-linter/README.md#install-vale-on-your-development-system "Install Vale on your development system - Angular documentation lint tool | angular/angular | Github"
130+
131+
[AngularLocalhost]: http://localhost:4200 "Angular.io on localhost"
132+
133+
<!--end links -->
134+
135+
@reviewed 2022-08-08

‎aio/content/guide/reviewing-content.md‎

Lines changed: 42 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,69 @@
1-
# Reviewing Content
1+
# Reviewing documentation
2+
3+
You can review the Angular documentation, even if you never contributed to Angular before.
24

35
Angular developers work best when they have access to accurate and complete documentation.
4-
Keeping existing content up-to-date is an essential part of ensuring that all developers have a great documentation experience.
6+
Keeping existing documentation up-to-date is an essential part of ensuring that all developers have a great development experience.
57

6-
This topic describes how you can help keep Angular content up-to-date by reviewing content.
8+
This topic describes how you can help keep the Angular documentation up-to-date by reviewing and updating it.
79

810
## Before you begin
911

10-
You can review content even if you've never contributed to Angular before.
11-
However, you may find it helpful to have the [Contributing to Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md) guide available if you're filing your first pull request in the repository.
12+
Review the [Documentation contributor guide][AioDocContributorGuide] to get ready to review to update the documentation.
13+
The *Documentation contributor guide* describes how to prepare to update a documentation topic.
14+
15+
You can edit a topic in the GitHub web interface or in your favorite code editor or integrated development environment (IDE).
16+
In either case, you want to edit in your own fork of the Angular source code repo.
17+
18+
To review a documentation topic, you want to be able to edit the topic.
19+
Even if you don't find any problem, you want to update the `@reviewed` tag at the end of the topic before you finish.
20+
21+
## Finding topics to review
1222

13-
## Reviewing content (`@reviewed`)
23+
Find topic a topic that has not been reviewed in the past six months.
1424

15-
All of the task-based guides, tutorials, and conceptual topics that you find on Angular.io support a `@reviewed` tag.
16-
When present, this tag is followed by the date representing when a given topic was reviewed for accuracy and completeness.
17-
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.
25+
At the bottom of some topics, there's an `@reviewed` tag that shows the date it was last reviewed.
26+
This is an example of such a tag taken from the bottom of a topic.
1827

1928
<div class="lightbox">
2029

21-
<img alt="Example of the last reviewed date specifying the day of the week, the month, the date, and the year on a page footer." src="generated/images/guide/contributors-guide/last-reviewed.png">
30+
<img alt="Example of the last reviewed date entry showing the date the topic was reviewed as month, day, and year" src="generated/images/guide/contributors-guide/last-reviewed.png">
2231

2332
</div>
2433

25-
This reviewed date indicates when someone last reviewed the topic to ensure that its contents were accurate.
34+
## Reviewing and updating a topic
2635

27-
You can review a topic using either the GitHub user interface or in an editor on your local machine.
28-
You can also review any topic that you like.
29-
Previous experience in the subject of the topic is helpful, but not required.
36+
To review a topic, use either the GitHub user interface or directly edit the source markdown file of the topic on your own computer.
3037

31-
**To review a topic:**
38+
Feel free to review any topic in which you have interest.
39+
Experience with the subject matter is helpful, but not required to provide copy edits.
3240

33-
1. Navigate to the topic that you want to review.
34-
1. Locate the last reviewed date at the bottom of the topic and verify that the topic meets the [review criteria](#review-criteria).
41+
**To review and update a documentation topic:**
3542

36-
If the topic does not have a last reviewed date, you are welcome to add it to the topic.
37-
To add a date, use the `YYYY-MM-DD` date format.
38-
Example:
39-
`@reviewed 2021-03-23`
43+
1. In your web browser, navigate to the topic that you want to review.
44+
2. Locate the last reviewed date at the bottom of the topic. Verify that the topic has not been reviewed within the past six months.
45+
3. Read through the topic.
46+
4. If the topic requires an update, you can:
47+
* [File an issue][GithubAngularAngularBlobMainContributingMdSubmitIssue] that describes the update required.
48+
* Fix the issue and [create a pull request][GithubAngularAngularBlobMainContributingMdSubmitPr] with the update.
49+
5. If the topic is accurate and doesn't need any revision, update, or add the `@reviewed` tag followed by the date you reviewed the topic. You can do this:
50+
* By using the [GitHub user interface][AioGuideUpdatingContentGithubUi]
51+
* By editing the file on your computer and creating a [standard pull request process][GithubAngularAngularBlobMainContributingMdSubmitPr] for Angular.
4052

41-
1. Read through the topic.
42-
1. If the topic requires an update, either [file an issue](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-issue) that describes the update required, or [create a pull request](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-pr) with the update.
43-
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/main/CONTRIBUTING.md#submit-pr).
44-
45-
<a id="review-criteria"></a>
53+
<!-- links -->
4654

47-
### Review criteria
55+
[AioDocContributorGuide]: guide/contributors-guide-overview "Documentation contributors guide | Angular"
4856

49-
In general, topics should be reviewed either every six months, or around every major release.
57+
[AioGuideReviewingContentReviewCriteria]: guide/reviewing-content#review-criteria "Review criteria - Reviewing content | Angular"
5058

51-
<!-- links -->
59+
[AioGuideUpdatingContentGithubUi]: guide/updating-content-github-ui "Updating topics through the GitHub user interface | Angular"
5260

5361
<!-- external links -->
5462

63+
[GithubAngularAngularBlobMainContributingMd]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md "Contributing to Angular | angular/angular | Github"
64+
[GithubAngularAngularBlobMainContributingMdSubmitIssue]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-issue "Submitting an Issue - Contributing to Angular | angular/angular | GitHub"
65+
[GithubAngularAngularBlobMainContributingMdSubmitPr]: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-pr "Submitting a Pull Request (PR) - Contributing to Angular | angular/angular | GitHub"
66+
5567
<!-- end links -->
5668

57-
@reviewed 2022-02-28
69+
@reviewed 2022-08-08

‎aio/content/images/guide/contributors-guide/topic-edit-icon.png‎

361 Bytes
Loading

0 commit comments

Comments
 (0)