Tidy up READMEs

CONTRIBUTING.md

@@ -10,21 +10,23 @@ Our team will keep hacking on Klaxon in spare moments, and we plan to keep it hu
 
 There are several ways you can help improve Klaxon, even if you’re not a coder or you’ve never contributed to an open source project before. You can:
 
-Help us spot bugs, including typos, and let us know by [filing an issue in Github](https://github.com/themarshallproject/klaxon/issues). If you’ve never used Github, don’t worry. Here’s a really good, quick [tutorial about discussing projects in Github Issues](https://youtu.be/KlrJVSJRUN4). Even if you’re an experienced Github user, this blog post provides some great advice on the [best practices of creating an issue](https://wiredcraft.com/blog/how-we-write-our-github-issues/).
+Help us spot bugs, including typos, and let us know by [filing an issue in GitHub](https://github.com/themarshallproject/klaxon/issues). If you’ve never used GitHub, don’t worry. Here’s a really good, quick [tutorial about discussing projects in GitHub Issues](https://youtu.be/KlrJVSJRUN4). Even if you’re an experienced GitHub user, this blog post provides some great advice on the [best practices of creating an issue](https://wiredcraft.com/blog/how-we-write-our-github-issues/).
 
-Help test the web interface, sharing feedback with us directly [in an email](mailto:klaxon-reports@themarshallproject.org) or in a Github issue.
-Help prioritize new features for the community to work on together next, by commenting on ones you like in [our Github issues](https://github.com/themarshallproject/klaxon/issues).
+Help test the web interface, sharing feedback with us directly [in an email](mailto:klaxon-reports@themarshallproject.org) or in a GitHub issue.
+Help prioritize new features for the community to work on together next, by commenting on ones you like in [our GitHub issues](https://github.com/themarshallproject/klaxon/issues).
 
 ### Contribute code
 
-We’re especially excited about other journalist-developers contributing code to flesh out the project and to add new features. Our motto is, “PULL REQUESTS GLADLY ACCEPTED.”
+We’re especially excited about other journalist-developers contributing code to flesh out the project and to add new features.
 
-If you want to contribute, start by reviewing this advice, inspired by this post on [the Codacy blog](http://blog.codacy.com/2015/12/17/open-source-development-a-few-guidelines/) and [Shauna Gordon-McKeon’s PyCon 2015 talk](https://shaunagm.github.io/personal/pycon2015.html). Before you do anything, read the documentation in our Github repo, particularly this CONTRIBUTING.md file and our [Code of Conduct](CODE_OF_CONDUCT.md). Once you’ve done that, you’re ready to engage with the community, by commenting on issues and participating in the process.
+If you want to contribute, start by reviewing this advice inspired by this post on [the Codacy blog](http://blog.codacy.com/2015/12/17/open-source-development-a-few-guidelines/) and [Shauna Gordon-McKeon’s PyCon 2015 talk](https://shaunagm.github.io/personal/pycon2015.html).
 
-Look for [issues](https://github.com/themarshallproject/klaxon/issues) in Klaxon’s Github repo tagged "help wanted" or “first-timer-friendly”. After you announce you’re working on an issue with a comment, fork the project. If you need help getting Klaxon running on a local development server, [follow these directions](DEVELOPING.md). Create a new branch for your feature, write a patch and send a pull request to us on Github. 
+Before you do anything, read the documentation in our GitHub repo, particularly this CONTRIBUTING.md file and our [Code of Conduct](CODE_OF_CONDUCT.md). You’re now ready to engage with the community by commenting on issues and participating in the process.
 
-You can expect that we'll acknowledge your patch and respond with questions or comments, and we’ll expect that you’ll remain engaged with the issue, responding to our questions in a timely manner and iterating on the code until the patch is merged or otherwise closed.
+Look for [issues](https://github.com/themarshallproject/klaxon/issues) in Klaxon’s GitHub repo tagged "help wanted" or “first-timer-friendly”. If you need help getting Klaxon running on a local development server, [follow these directions](DEVELOPING.md). Create a new branch for your feature, write a patch and send a pull request to us on GitHub.
+
+We should acknowledge your patch and respond with questions or comments, and we’ll expect that you’ll remain engaged with the issue, responding to our questions in a timely manner and iterating on the code until the patch is merged or otherwise closed.
 
 ### Discuss
 
-One of the things we’re most excited about as we release Klaxon is seeing how other newsrooms put it to use. We’ll be eager to hear from you about your experiences with the tool. There are several ways we can discuss this together. You can email us directly at [klaxon-reports@themarshallproject.org](mailto:klaxon-reports@themarshallproject.org). We also have a [Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users) where Klaxon users and developers working on the project can talk. Users can ask questions of one another, and contributors can discuss changes to the code and adding new functionality. Finally, you can always open or comment on an item in our [Github repo’s issue tracker](https://github.com/themarshallproject/klaxon/issues).
+One of the things we’re most excited about as we release Klaxon is seeing how other newsrooms put it to use. We’ll be eager to hear from you about your experiences with the tool. There are several ways we can discuss this together. You can email us directly at [klaxon-reports@themarshallproject.org](mailto:klaxon-reports@themarshallproject.org). We also have a [Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users) where Klaxon users and developers working on the project can talk. Users can ask questions of one another, and contributors can discuss changes to the code and adding new functionality. Finally, you can always open or comment on an item in our [GitHub repo’s issue tracker](https://github.com/themarshallproject/klaxon/issues).

DEVELOPING.md

@@ -2,15 +2,11 @@
 
 If you're interested in [helping improve Klaxon by contributing code](CONTRIBUTING.md), this is a quick guide to how to get it running on your local machine for development.
 
-First, we'll assume you already have git on your local machine, as well as a standard postgres installation (if you need a [quick way to get Postgres up and running, try this](https://postgresapp.com/)). So go to your terminal, navigate to whatever directory where you keep your projects and clone the Klaxon repo.
+First, we'll assume you already have git on your local machine, as well as PostgreSQL (if you need a [quick way to get Postgres up and running, try this](https://postgresapp.com/)). Go to your terminal, navigate to the directory where you keep projects and clone the Klaxon repository.
 
-```
-git clone git@github.com:themarshallproject/klaxon.git
-```
+After you've cloned it move into the Klaxon directory. If you're on a Mac, you'll need to already have [homebrew](https://brew.sh/) and [rbenv](https://github.com/rbenv/rbenv) (a program that manages versions of Ruby) installed. Then you'll want
 
-After you've cloned it, `cd` into the Klaxon directory. If you're on a Mac, you'll need to already have [homebrew](https://brew.sh/) and [rbenv](https://github.com/rbenv/rbenv) (a program that manages versions of Ruby) installed. Then you'll want
-
-These next commands will put the proper (albeit aged) version of Ruby that Klaxon requires on your machine and make it available in this repo's directory.
+These next commands will install the version of Ruby that Klaxon requires on your machine and make it available in this directory.
 
 ```
 brew update && brew upgrade ruby-build
@@ -31,29 +27,27 @@ ADMIN_EMAILS="my_awesome_email@gmail.com"
 HOST='localhost:5000'
 ```
 
-Feel free to substitute in your email address. In development, Klaxon doesn't actually send emails locally, so a real address is not required.
-
-Now that's set, you'll run a couple of commands for Rails to create Klaxon's database on your machine.
+Feel free to substitute in your email address. In development, Klaxon doesn't actually send emails locally so a real address is not required. You just need to make sure you use exactly the same thing when you log in to the admin interface locally. With that set you'll run a couple of commands to create Klaxon's database on your machine.
 
 ```
 bin/rake db:create
 bin/rake db:migrate
 ```
 
-Now, you should be about ready to get started. This command in the top folder of the Klaxon repo will get your dev server rolling.
+You're about ready to get started. This command in the top folder of the Klaxon repo will start the development server.
 
 ```
 bin/dev
 ```
 
-Now, you should be able to go to [localhost:5000](http://localhost:5000/) in your web browser and see Klaxon's welcome screen pop up. You'll want to manually add a webpage or two to watch at [watching/pages/new](http://localhost:5000/watching/pages/new). For development purposes, you'll probably want to pick a site that updates pretty regularly. We use [http://www.timeanddate.com/](http://www.timeanddate.com/).
+Visit [localhost:5000](http://localhost:5000/) in your web browser and you should see Klaxon's welcome screen. Log in using the email you set above. Try to manually add a webpage or two at [watching/pages/new](http://localhost:5000/watching/pages/new). For development purposes you'll probably want to pick a site that updates pretty regularly — we use [http://www.timeanddate.com/](http://www.timeanddate.com/).
 
-To get Klaxon to check for updates on the pages you're watching, in another terminal window, run this rake command.
+To get Klaxon to check for updates on the pages you're watching, in another terminal window run this command:
 
 ```
 rake check:all
 ```
 
-Now, when you go to the main Klaxon page, you should start to see changes in the Feed of the latest updates.
+When you go to the main Klaxon page you should see new changes in the feed.
 
-Go forth and add some features, and be sure to send us your [pull requests](/pulls) for features you think other Klaxon users might find handy.
+Go forth and add some new features!

HEROKU_UPGRADE.md

@@ -1,11 +1,13 @@
-Those of you who are still running Klaxon on free Heroku tiers have likely received messages telling you that the free services will soon be wound down. We have considered a few options to work around this, but we haven't found a good way to mitigate this issue while keeping Klaxon as easy to deploy and maintain as can be. After six years of being able to run this at no cost at all, it looks like you will now have to pay a small fee to continue to do so. We will keep investigating other avenues for the future of Klaxon, but for now, you'll have to pay. 
+# Heroku Transition Guide
 
-On Nov. 28th, Heroku will stop running free apps, so you have to make a couple of small tweaks to your setup before then. Here's what you'll need to do: 
+Those of you who are still running Klaxon on free Heroku tiers have likely received messages telling you that the free services will soon be wound down. We have considered a few options to work around this, but we haven't found a good way to mitigate this issue while keeping Klaxon as easy to deploy and maintain as can be. After six years of being able to run this at no cost at all, it looks like you will now have to pay a small fee to continue to do so. We will keep investigating other avenues for the future of Klaxon, but for now, you'll have to pay.
+
+On Nov. 28th, Heroku will stop running free apps, so you have to make a couple of small tweaks to your setup before then. Here's what you'll need to do:
 
 - Log into your Heroku dashboard at https://dashboard.heroku.com/apps/
 - Click on your Klaxon app
 - Click the "Resources" tab along the top of the page (between "Overview" and "Deploy")
 - You should see a list of services that run as part of your setup. First, you'll need to click "Change Dyno Type" It will present you with a menu of options. You'll probably want to choose "Eco". This will cost you $5 per month and can be shared across several apps, if you're using Heroku for any other free programs. It will also put your web app to sleep if someone doesn't visit for 30 minutes (this is the same way the free-tier dynos worked). But it should keep your Klaxon scheduler and notifier running as expected.
 - Many of you have likely already outgrown the 10,000-row database limit for the free Postgres starter plan. If, however, you're still using that free database, you'll need to upgrade that too. Look at the line that says "Heroku Postgres". You should see an orange alert on the right-hand side of the table that reads "Hobby Dev". Click the menu button to the right of the word "Free" and choose "Modify Plan". There you'll need to change your plan name from "Hobby Dev" to "Mini" and click "Provision". The Mini Postgres plan costs about $5 a month for 10,000 rows. When you outgrow that database, you can upgrade to the Basic Postgres plan for about $9 a month.
 
-We hope this helps you get everything sorted to keep your Klaxon running. If you have questions or need a hand with these changes, reach out to Tom directly, and we'll do our best to help you troubleshoot.
+We hope this helps you get everything sorted to keep your Klaxon running. If you have questions or need a hand with these changes, reach out to Tom directly, and we'll do our best to help you troubleshoot.