mirror of
https://github.com/nickpoida/og-aws.git
synced 2025-02-15 03:11:57 +00:00
A couple process things (#260)
* A few more suggestions on PR review. * Remove Airtable links. They're not used widely enough to merit such prominence. * Review fixes.
This commit is contained in:
Joshua Levy
Thanos Baskous
parent
718120db32
commit
3f5051c761
2 changed files with 49 additions and 31 deletions
|
|
@ -1,24 +1,29 @@
|
|||
Contributing
|
||||
------------
|
||||
|
||||
[](https://og-aws.slack.lexikon.io/) [](https://airtable.com/shrXZ61VrovWfXYBg)
|
||||
[](https://og-aws.slack.lexikon.io/)
|
||||
|
||||
Contributions of all kinds, including discussion, corrections, additions, and improvements, are welcome! We hope you'll join and help, in small ways or large. We gladly [credit](/AUTHORS.md) all contributors. Here are few notes before you jump in.
|
||||
|
||||
### Please Help
|
||||
Please Help
|
||||
-----------
|
||||
|
||||
If you’ve found this guide useful, you have many ways to help:
|
||||
If you’ve found this guide useful, please join us:
|
||||
|
||||
- The simplest thing you can do to contribute is [**join the Slack channel**](https://og-aws.slack.lexikon.io/) or [**add to our list of common questions**](https://airtable.com/shrXZ61VrovWfXYBg), which helps the community and guides what contributors can focus on. We encourage you to ask AWS questions and help others!
|
||||
- The simplest thing you can do to contribute is [**join the Slack channel**](https://og-aws.slack.lexikon.io/) and **ask or answer questions** or **discuss**, which
|
||||
helps the community and guides what contributors can focus on.
|
||||
- [**File issues**](https://github.com/open-guides/og-aws/issues) if it’s clear something needs to be improved and you’re not able to make a pull request.
|
||||
- [**Pull requests**](https://github.com/open-guides/og-aws/pulls) with changes are always welcome. Please keep them small and focused, so we can add items individually, and review the conventions below. If you want to make a larger change, try to discuss it in Slack.
|
||||
- **Review** or **comment** on existing issues and pull requests if you have expertise.
|
||||
- If you have deep expertise, we may ask you to be an **editor** or **expert**. Editors and experts are assigned roles that [help us review](#editorial-process) the Guide. Join Slack to discuss this.
|
||||
|
||||
Making Contributions
|
||||
--------------------
|
||||
|
||||
### Pull Request Etiquette
|
||||
|
||||
- Keep changes as small as is practical. Do not make changes to multiple sections at once, alter whitespace in broad ways, etc.
|
||||
- Neutrality: If you have an affiliation related to what you are changing, please disclose it.
|
||||
- **Neutrality:** If you have an affiliation related to what you are changing, please mention it.
|
||||
- Please do your best to review current issues and pull requests to avoid duplication.
|
||||
|
||||
### Writing Style
|
||||
|
|
@ -28,7 +33,31 @@ If you’ve found this guide useful, you have many ways to help:
|
|||
- **Include opinions and common practice:** Thoughtful opinion is helpful. If there are multiple conventions or ideas on something held by experts, mention the different ones.
|
||||
- **Clarity:** Strive for consistency with conventions listed here, but clarity is most important.
|
||||
|
||||
### Writing Conventions
|
||||
### Pull Request Review
|
||||
|
||||
When creating a PR or reviewing one, it’s helpful to consider a few questions:
|
||||
|
||||
1. Are relevant docs linked (AWS and third party blogs)?
|
||||
2. Can more details be added without lengthening it significantly?
|
||||
3. Can the same information be conveyed with more succinctly or more clearly?
|
||||
4. Copy editing: Does it match the [writing style](#writing-style) and [conventions](#writing-conventions) (including emoji symbols, punctuation, and grammar)?
|
||||
5. Are there any other parts of the guide that should be updated at the same time? (Examples are adding new sections to the table of contents, adding new internal links, rows to tables, etc.)
|
||||
6. Are there additional improvements that should be filed as issues?
|
||||
|
||||
### Editorial Process
|
||||
|
||||
- Roles:
|
||||
- **Project leads:** Own overall quality of the Guide, direction, and process.
|
||||
- **Editors:** Contributors own specific sections or aspects of the Guide, reviewing PRs and/or writing. Requires expert knowledge.
|
||||
- **Experts:** People with expert knowledge in various areas, who have agreed to review or help on demand with tougher questions or PRs.
|
||||
- **Contributors:** Everyone who contributes content or helps one way or another.
|
||||
- All PRs are reviewed by an **editor** and for non-trivial changes, a **project lead**, usually in that order, but it can be reversed for expediency.
|
||||
- In addition, anyone with relevant knowledge is encouraged to review/comment on PRs.
|
||||
- Both editors and project leads are responsible for checking for style or problems.
|
||||
- Trivial changes (including copy editing) may be merged in directly by project leads or editors.
|
||||
|
||||
Writing Conventions
|
||||
-------------------
|
||||
|
||||
When you contribute, keep in mind these conventions:
|
||||
|
||||
|
|
@ -53,18 +82,7 @@ When you contribute, keep in mind these conventions:
|
|||
|
||||
Note we keep consistent formatting in Markdown via [markdownfmt](https://github.com/shurcooL/markdownfmt). We run **admin/reformat.sh** to do this, but you don’t have to worry about it unless you really want to.
|
||||
|
||||
### Editorial Process
|
||||
|
||||
- Roles:
|
||||
- **Project leads:** Own overall quality of the Guide, direction, and process.
|
||||
- **Editors:** Contributors own specific sections or aspects of the Guide, reviewing PRs and/or writing. requires expert knowledge.
|
||||
- **Experts:** People with expert knowledge in various areas, who have agreed to review or help on demand with tougher questions or PRs.
|
||||
- **Contributors:** Everyone who contributes content or helps one way or another.
|
||||
- All PRs are reviewed by an **editor** and for non-trivial changes, a **project lead**, usually in that order, but it can be reversed for expediency.
|
||||
- In addition, anyone with relevant knowledge is encouraged to review/comment on PRs.
|
||||
- Both editors and project leads are responsible for checking for style or problems.
|
||||
- Trivial changes (including copy editing) may be merged in directly by project leads or editors.
|
||||
|
||||
### Contact
|
||||
Contact
|
||||
-------
|
||||
|
||||
If you have concerns or additional ideas of ways to help, e-mail **og-aws@lexikon.io** or use Slack to contact the [project leads](AUTHORS.md).
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
The Open Guide to Amazon Web Services
|
||||
=====================================
|
||||
|
||||
[](https://og-aws.slack.lexikon.io/) [](https://airtable.com/shrXZ61VrovWfXYBg)
|
||||
[](https://og-aws.slack.lexikon.io/) ⇦ Join us!
|
||||
|
||||
[Credits](AUTHORS.md) ∙ [Contributing guidelines](CONTRIBUTING.md)
|
||||
|
||||
|
|
@ -93,9 +93,9 @@ Before using the guide, please read the [**license**](#license) and [**disclaime
|
|||
|
||||
**This is an early in-progress draft!** It’s our first attempt at assembling this information, so is far from comprehensive still, and likely to have omissions or errors.
|
||||
|
||||
[](https://og-aws.slack.lexikon.io/) [](https://airtable.com/shrXZ61VrovWfXYBg)
|
||||
[](https://og-aws.slack.lexikon.io/)
|
||||
|
||||
Please help by [**joining the Slack channel**](https://og-aws.slack.lexikon.io/) to talk about AWS (anyone is welcome, even if you only have questions!), [**submitting a question**](https://airtable.com/shrXZ61VrovWfXYBg), or [**contributing to the guide**](CONTRIBUTING.md). This guide is *open to contributions*, so unlike a blog, it can keep improving. Like any open source effort, we combine efforts but also review to ensure high quality.
|
||||
Please help by [**joining the Slack channel**](https://og-aws.slack.lexikon.io/) (we like to talk about AWS in general, even if you only have questions — discussion helps the community and guides improvements) and [**contributing to the guide**](CONTRIBUTING.md). This guide is *open to contributions*, so unlike a blog, it can keep improving. Like any open source effort, we combine efforts but also review to ensure high quality.
|
||||
|
||||
Scope
|
||||
-----
|
||||
|
|
|
|||
Loading…
Reference in a new issue