AWS Documentation is Now Open Source and on GitHub
- March 14, 2018
Earlier this year we made the AWS SDK developer guides available as GitHub repos (all found within the awsdocs organization) and invited interested parties to contribute changes and improvements in the form of pull requests.
Today we are adding over 138 additional developer and user guides to the organization, and we are looking forward to receiving your requests. You can fix bugs, improve code samples (or submit new ones), add detail, and rewrite sentences and paragraphs in the interest of accuracy or clarity. You can also look at the commit history in order to learn more about new feature and service launches and to track improvements to the documents.
Making a Contribution
Before you get started, read the Amazon Open Source Code of Conduct and take a look at the Contributing Guidelines document (generally named
CONTRIBUTING.md) for the AWS service of interest. Then create a GitHub account if you don’t already have one.
Once you find something to change or improve, visit the HTML version of the document and click on Edit on GitHub button at the top of the page:
This will allow you to edit the document in source form (typically Markdown or reStructuredText). The source code is used to produce the HTML, PDF, and Kindle versions of the documentation.
Once you are in GitHub, click on the pencil icon:
This creates a “fork” — a separate copy of the file that you can edit in isolation.
Next, make an edit. In general, as a new contributor to an open source project, you should gain experience and build your reputation by making small, high-quality edits. I’ll change “dozens of services” to “over one hundred services” in this document:
Then I summarize my change and click Propose file change:
I examine the differences to verify my changes and then click Create pull request:
Then I review the details and click Create pull request again:
The pull request (also known as a PR) makes its way to the Elastic Beanstalk documentation team and they get to decide if they want to accept it, reject it, or to engage in a conversation with me to learn more. The teams endeavor to respond to PRs within 48 hours, and I’ll be notified via GitHub whenever the status of the PR changes.
As is the case with most open source projects, a steady stream of focused, modest-sized pull requests is preferable to the occasional king-sized request with dozens of edits inside.
If I am interested in tracking changes to a repo over time, I can Watch and/or Star it:
If I Watch a repo, I’ll receive an email whenever there’s a new release, issue, or pull request for that service guide.
Go Fork It
This launch gives you another way to help us to improve AWS. Let me know what you think!