Skip to content

Commit

Permalink
docs: add contributors guide to aio
Browse files Browse the repository at this point in the history
  • Loading branch information
David Shevitz committed Mar 3, 2021
1 parent 96f15f0 commit 6be5190
Show file tree
Hide file tree
Showing 5 changed files with 108 additions and 0 deletions.
33 changes: 33 additions & 0 deletions aio/content/guide/contributors-guide-overview.md
@@ -0,0 +1,33 @@
# 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

<div class="card-container">
<a href="guide/reviewing-content" class="docs-card"
title="Reviewing content">
<section>Reviewing content</section>
<p>Keep Angular content up-to-date by reviewing topics for accuracy.</p>
<p class="card-footer">Reviewing content</p>
</a>
<a href="" class="docs-card"
title="Updating search terms">
<section>Updating search terms</section>
<p>Help Angular developers by improving the search terms for existing topics.</p>
<p class="card-footer">Updating search terms</p>
</a>
<a href="" class="docs-card"
title="Documentation Style Guide">
<section>Documentation style guide</section>
<p>Review the syntax and styles used within the Angular documentation set.</p>
<p class="card-footer">Documentation style guide</p>
</a>
</div>

63 changes: 63 additions & 0 deletions aio/content/guide/reviewing-content.md
@@ -0,0 +1,63 @@
# 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 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.

<div class="lightbox">
<img src="generated/images/guide/contributors-guide/last-reviewed.png" alt="Example of the last reviewed date on a page footer.">
</div>

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 the command line 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.

{@a review-criteria}
### Review criteria

In general, topics should be reviewed either every six months, or around every major release.

On occasion, topics might require a more frequent review. However, we request that you do not file unnecessary pull requests for reviewing content.

### Reviewing a topic using the GitHub user interface

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 that describes the update required, or create a pull request with the update.

1. After you have read the topic, click the edit icon at the top of the topic.

<div class="lightbox">
<img src="generated/images/guide/contributors-guide/edit-icon.png" alt="The edit icon for an Angular topic.">
</div>

A GitHub page appears, displaying the source of the topic.

1. At the bottom of the topic, add or update the `@reviewed` tag, using the date format of `YYYY-MM-DD`. For example: `@reviewed 2021-03-02`.

1. At the bottom of the screen, update the Commit Changes box with a description of the change. Use the format `docs: update reviewed date`.

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.

Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions aio/content/navigation.json
Expand Up @@ -959,6 +959,18 @@
"url": "guide/styleguide",
"title": "Coding Style Guide",
"tooltip": "Guidelines for writing Angular code."
}
]
},
{
"url": "guide/contributors-guide-overview",
"title": "Content Contributor's Guide",
"tooltip": "Describes how to contribute to the Angular documentation.",
"children": [
{
"url": "guide/reviewing-content",
"title": "Reviewing content",
"tooltip": "Keep Angular content up-to-date by reviewing topics for accuracy."
},
{
"url": "guide/docs-style-guide",
Expand Down

0 comments on commit 6be5190

Please sign in to comment.