Merge pull request #5 from GSA/jrc_toolkit-proofing

AminPIC · web-flow · commit d63a0171c5fa · 2020-02-21T11:57:10.000-05:00
Global updates to Toolkit docs
diff --git a/.DS_Store b/.DS_Store
diff --git a/.gitignore b/.gitignore
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -40,8 +40,8 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html.
 
 [homepage]: https://www.contributor-covenant.org
 
-For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
+For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq.
diff --git a/README.md b/README.md
@@ -1,16 +1,14 @@
-# Open source playbook and toolkit
-### By [Code.gov](https://code.gov/) for federal agencies
-
-&nbsp;
+# Federal Source Code and Open Source Toolkit
+**By [Code.gov](https://code.gov/) for federal agencies**
 
 ## Description:
-This is a government-wide project facilitated by the [Code.gov](https://code.gov/) team to produce a playbook and toolkit pertaining to open sourcing software (OSS).
+This is a government-wide project facilitated by the [Code.gov](https://code.gov/) team to produce a toolkit pertaining to open source software (OSS).
 
-Excerpt from the initial Open Source Playbook & Tookit Working Group write-up.
+Excerpt from the initial Open Source Tookit Working Group write-up.
 
-> In the Code.gov open source inventory we are seeing an ongoing issue where agencies are publishing their open source code, but the projects are not set up in a way which makes the code reusable.  In order to better align agency projects with the goals of the Federal Source Code Policy, the Code.gov team is launching an open source playbook and toolkit. We’re hoping to provide additional resources for open source maintainers to help support the growing community.
+> In the Code.gov open source inventory we are seeing an ongoing issue where agencies are publishing their open source code, but the projects are not set up in a way which makes the code reusable.  In order to better align agency projects with the goals of the Federal Source Code Policy, the Code.gov team is launching this toolkit. We believe it offers additional resources for open source maintainers to help support a growing community.
 
-> The goal is to provide info, examples and resources on what really well managed open source projects look like and to give additional federal guidance for developers to follow when publishing projects.
+> The goal is to provide info, examples, and resources on what really well managed open source projects look like and to give additional federal guidance for developers to follow when publishing projects.
 
 Additional content urging us to begin this effort can be found in the [background docs](background_docs) section including the [Harvard Engagement Report](background_docs/HarvardEngagementReport.pdf), a recent [UX study](background_docs/Always%20Improving_Making%20the%20Contribution%20to%20Repos%20Better.pdf) we conducted and blogged about, and [Q&A](background_docs/Open%20Source%20Playbook%20Q%26A%20-%2024%20June%202019.pdf) from the first meeting with agencies before official kick-off.
 
diff --git a/automation.md b/automation.md
@@ -9,7 +9,7 @@ Don’t make standards too complicated or that they increase barriers to contrib
 
 **Maintenance work**
 * [Semantic-release](https://github.com/semantic-release/semantic-release) automates releases
-* [mention-bo](https://github.com/facebook/mention-bot)t mentions potential reviewers for pull requests
+* [mention-bot](https://github.com/facebook/mention-bot) mentions potential reviewers for pull requests
 * [Danger](https://github.com/danger/danger) helps automate code review
 * [Issue templates and pull request templates](https://github.com/blog/2111-issue-and-pull-request-templates)
 * Style guides
@@ -21,6 +21,4 @@ Don’t make standards too complicated or that they increase barriers to contrib
 * GitHub’s [Tools for Open Source](https://github.com/collections/tools-for-open-source) – software to make running an open source project a little easier
 * GitHub’s [issue templates and pull request templates](https://github.com/blog/2111-issue-and-pull-request-templates)
 * [Semantic-release](https://github.com/semantic-release/semantic-release) automates releases
-* [mention-bot](https://github.com/facebook/mention-bot) mentions potential reviewers for pull requests
-* [Danger](https://github.com/danger/danger) helps automate code review
 * [Kubernetes Development Automation](https://github.com/kubernetes/community/blob/master/contributors/devel/automation.md) documentation
diff --git a/community_building.md b/community_building.md
@@ -1,22 +1,23 @@
 # Community building and maintenance
 
 **Places to Congregate**
-It’s important to give your community a place to congregate to help them get to know each other. When communication is public and accessible, anyone can read past archives and get up to speed and participate. 
+It’s important to give your community a place to congregate to help them get to know each other and to contribute to code repositories. When communication is public and accessible, everyone can read past archives and get up to speed and participate. 
 
-Secondly, as a maintainer, if you don’t give people a public place to talk about your project, they will likely contact you directly. Public communication can be as simple as directing people to open an issue instead of emailing you directly or commenting on your blog.
+As a maintainer, you want to provide a public place for the community to discuss issues with code and submit pull requests (PRs) for review and inclusion in the current code base.
 
 Ideas for building community:
 
+* GitHub repository or similar public code sharing platform
 * Live chat (e.g., Slack channels, IRC, or Gitter)
 * Forum/thread-based communities (e.g., Discourse)
 * In-person meetups, conferences or events
-* GitHub issues or listserv
+* Community listserv
 * Office Hours
 * Social Media
 
 Notable exceptions to public communication are: 1) security issues and 2) sensitive code of conduct violations. People should be able to report these issues privately. 
 
-# Code Review
+## Code Review
 
 * All code in any code-base should look like a single person typed it, no matter how many people contributed. Principles of writing idiomatic JavaScript (WP-CLI)
 * Code review should probably always be your top priority, and you should figure out the best way to work it into your event loop (pending code review requests represent blocked threads of execution)
