Update README and CONTRIBUTING documents

For formatting and grammar.

Change-Id: I2ff64fe16d735d431420db6e9c7e5a31de057ec2
Signed-off-by: Dan Cross <crossd@gmail.com>

CONTRIBUTING.md

@@ -1,46 +1,68 @@
 # How to contribute
 
-I'm really glad you're reading this, because we need volunteer developers to help this project come to fruition.
+We are glad you are reading this, because we need volunteer developers
+to help this project come to fruition.
 
-If you don't have anything you are working on we have a [**list of newbie friendly issues**](https://github.com/Harvey-OS/harvey/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+label%3A%22newbie+friendly%22) you can help out with.
+If you don't have anything you are working on we have a
+[**list of newbie friendly issues**](https://github.com/Harvey-OS/harvey/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+label%3A%22newbie+friendly%22)
+you can help out with.
 
-If you haven't already, come find us on our [mailing list](https://groups.google.com/forum/#!forum/harvey). We want you working on things you're excited about.
+If you haven't already, come find us on our
+[mailing list](https://groups.google.com/forum/#!forum/harvey). We
+want you working on things you're excited about.
 
-Harvey, like most other open source projects, has a [Code of Conduct](https://github.com/Harvey-OS/harvey/wiki/Code-of-Conduct) that it expects its contributors and core team members to adhere to.
+Harvey, like most other open source projects, has a
+[Code of Conduct](https://github.com/Harvey-OS/harvey/wiki/Code-of-Conduct)
+that it expects its contributors and core team members to adhere to.
 
 Here are some important resources:
 
-  * [Mailing list](https://groups.google.com/forum/#!forum/harvey) is where the development discussion happens.
-  * [Man Pages](https://sevki.io/harvey/sys/man/1/0intro) are where you can read man pages from head of the repo.
-  * [Issue Tracker](https://github.com/Harvey-OS/harvey/issues) is our day-to-day project management space.
+  * Our [mailing list](https://groups.google.com/forum/#!forum/harvey)
+    is where the development discussion happens.
+  * [Man Pages](https://sevki.io/harvey/sys/man/1/0intro) are where
+    you can documentation from head of the repository.
+  * The [Issue Tracker](https://github.com/Harvey-OS/harvey/issues) is
+    our day-to-day project management space.
 
 
 ## Testing
 
-We make sure Travis-CI can build your pull-requests before we can accept your contributions.
+We make use Travis-CI and make sure we can build your pull-requests
+before we can accept your contributions.
 
 ## Submitting a patch
 
 Harvey uses Github Pull Requests to accept contributions.
 
-1.  Clone the repo `git clone https://github.com/Harvey-OS/harvey.git`. It is also possible to use git instead of https when you have an SSH public key stored in Github. Then you clone the repo with `git clone git@github.com:Harvey-OS/harvey.git`. This makes later submissions easier. For the rest of this manual we assume to use https.
-2.  Check out a feature branch you will work on by `git checkout -b feature-name` for instance for issue #70, @keedon selected the branch name `statscrash`.
+1.  Clone the repository:
+	`git clone https://github.com/Harvey-OS/harvey.git`.
+	It is also possible to use `git` instead of `https` if you have an
+    SSH public key stored on Github:
+	`git clone git@github.com:Harvey-OS/harvey.git`.
+	This makes submitting contributions easier. For the rest of this
+    manual we assume to use https.
+2.  Check out a feature branch for your work on by executing:
+	`git checkout -b feature-name`.
+	For example, @keedon selected the branch name `statscrash` for
+    issue #70.
 3.  Make changes
-4.  Commit with a descriptive message, like so
+4.  Commit with a descriptive message:
     ```
     $ git commit -m "A brief summary of the commit
     >
     > A paragraph describing what changed and its impact."
     ```
-    take a look at @keedon's [commit message](https://github.com/keedon/harvey/commit/09fe3a21fa8b42088bc8ad83287928e9e7cc96ef) for the same issue for a good example of a descriptive commit message.
-    You can also use graphical git tools such as `git gui` which make commiting changes easier.
+    For a representative example, look at @keedon's
+	[commit message](https://github.com/keedon/harvey/commit/09fe3a21fa8b42088bc8ad83287928e9e7cc96ef)
+	for issue #70 mentioned above. You can also use graphical git
+    tools such as `git gui` if you like.
 5.  Fork the repo (only once).
     ![harvey-os_harvey__a_fresh_take_on_plan_9](https://cloud.githubusercontent.com/assets/429977/13457174/099fb5cc-e067-11e5-83ce-f65aa966a4a9.png)
-6.  Add the repo as a remote (every time you clone the repo)
+6.  Add the repo as a remote (every time you clone the repository)
 
     `git remote add yourname https://github.com/yourusername/harvey.git`
 
-    where "yourname" is the name of your github login.
+    where "yourname" is your github login name.
 
     `git remote -v` should look like this:
     ```
@@ -50,25 +72,49 @@ Harvey uses Github Pull Requests to accept contributions.
     origin https://github.com/Harvey-OS/harvey.git (fetch)
     origin https://github.com/Harvey-OS/harvey.git (push)
     ```
-7.  Push your branch to your forked repo like so `git push yourname feature-name`
-8.  Create a pull request by going to `https://github.com/yourname/harvey/pull/new/feature-name` or clicking the PR button
+7.  Push your branch to your forked repository:
+	`git push yourname feature-name`
+8.  Create a pull request by going to
+    `https://github.com/yourname/harvey/pull/new/feature-name`
+	or clicking the PR button
     ![sevki_harvey__a_64_bit_operating_system_based_on_plan_9_from_bell_labs_and_nix__under_gpl](https://cloud.githubusercontent.com/assets/429977/13457635/79359350-e069-11e5-987b-1b4fccc45372.png)
-9.  Add details of what you have worked on and what your intentions are.
+9.  Add details of what you have worked on and your motivation.
     ![comparing_harvey-os_master___sevki_travis-trials_ _harvey-os_harvey](https://cloud.githubusercontent.com/assets/429977/13457683/aa2a423a-e069-11e5-84cc-1173e33264cb.png)
-    When you send a pull request, we will love you forever if you include qemu outputs and more tests. We can always use more test coverage. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).
+    When you send a pull request, we greatly appreciate if you include
+    `emu` output and additional tests: we can always use more test
+    coverage. Please follow our coding conventions and make sure all
+    of your commits are atomic in the sense of having one feature per
+    commit.
 
 ### Iterating on your work
 
-- A Github PR or a Gerrit CL roughly serve the same purpose, they are feedback loops for people to give feedback and for you to iterate on your work, so be ready to repeat steps 3, 4 and 7.
-- When iterating on your work continue committing to the same branch and push the changes up to your fork. Github will track the changes and update the PR accordingly.
-- Most of the time while you have submitted your PR, someone else will have merged something to master, at which point your branch will have been outdated, GitHub provides a convenient way of updating your branch right from your pull request.
-![build_files_by_sevki_ _pull_request__53_ _harvey-os_harvey](https://cloud.githubusercontent.com/assets/429977/13457994/4d9a3118-e06b-11e5-9898-f8574b5ce11d.png)
-- When you click that button, GitHub will update your branch, at which point you will have to `git pull yourname feature-name` and update your local repo before committing more changes.
-- If your changes are conflicting with something that was merged into the branch, you will have to resolve the changes manually and submit the changes.
+- A Github pull request or a Gerrit CL roughly serve the same purpose:
+  they are feedback loops for people to give feedback and for you to
+  iterate on your work in response to that feedback, so be ready to
+  repeat steps!
+- When iterating on your work continue committing to the same branch
+  and push the changes up to your fork. Github will track the changes
+  and update the pull request accordingly.
+- Most of the time, when you are ready to submit your pull request,
+  someone else will have merged something to master, at which point
+  your branch will have been outdated, GitHub provides a convenient
+  way of updating your branch right from your pull request.
+  ![build_files_by_sevki_ _pull_request__53_ _harvey-os_harvey](https://cloud.githubusercontent.com/assets/429977/13457994/4d9a3118-e06b-11e5-9898-f8574b5ce11d.png)
+- When you click that button, GitHub will update your branch, at which
+  point you will have to `git pull yourname feature-name` and update
+  your local repo before committing more changes.
+- If your changes conflict with something that was merged into the
+  branch, you will have to resolve the changes manually before
+  submitting the changes.
 
 ### Keeping up to date with the master branch
 
-If you're working in a branch that is outdated with respect to the master branch, just do a `git pull --rebase`. This will put your changes after the pull. In the case that there would be conflicts, you will have to solve them manually, but they are marked with something like ">>>>>HEAD" and git will tell you about which files are conflicting.
+If you're working in a branch that is outdated with respect to the
+master branch, just do a `git pull --rebase`. This will put your
+changes after the pull. In the case that there would be conflicts, you
+will have to solve them manually, but they are marked with something
+like "`>>>>>HEAD`" and git will tell you about which files are in
+conflict.
 
 #### More information
 
@@ -84,11 +130,15 @@ If you're working in a branch that is outdated with respect to the master branch
 
 ## Coding conventions
 
-If you read the code you should get a hang of it but a loose listing of our [Style-Guide](https://github.com/Harvey-OS/harvey/wiki/Style-Guide) exists, we recommend you check it out.
+If you read the code you should get a hang of it but a loose listing
+of our
+[Style-Guide](https://github.com/Harvey-OS/harvey/wiki/Style-Guide)
+exists, we recommend you check it out.
 
-We have also automated the process via [clang-format](http://clang.llvm.org/docs/ClangFormat.html) so before you submit a change please format your diff.
+We have also automated the process via
+[clang-format](http://clang.llvm.org/docs/ClangFormat.html)
+so before you submit a change please format your diff.
 
 [How to clang-format a diff](http://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting)
 
-
 _Adopted from [Open Government Contribution Guidelines](https://github.com/opengovernment/opengovernment/blob/master/CONTRIBUTING.md)_

README

@@ -2,14 +2,29 @@
 Harvey: A Fresh Take on Plan 9
 =====
 
-Welcome to Harvey, we are delighted that you are interested in the project.
-
-- Take a look at the [Getting started](https://github.com/Harvey-OS/harvey/wiki/Getting-Started) guide to learn how to get Harvey and how to play with it.
-- You enjoyed playing with Harvey and you want to help out? Great! Take a look at our [Contribution Guide](https://github.com/Harvey-OS/harvey/blob/master/CONTRIBUTING.md). Contribution guide covers a wide variety of topics includding, Harvey coding style, [Code of Conduct](https://github.com/Harvey-OS/harvey/wiki/Code-of-Conduct), where to get help and so on.
-- We also cover a wide variety of topics on our [wiki](https://github.com/Harvey-OS/harvey/wiki) and [apex's wiki](https://github.com/Harvey-OS/apex/wiki).
-- If the information you are looking for doesn't exist on the wiki, ask the [Mailing list](https://groups.google.com/forum/#!forum/harvey) for help, it's where most of the conversation for development happens.
-- [Man Pages](https://sevki.io/harvey/sys/man/1/0intro) are where you can read man pages from the head of the repo.
-- Harvey also has a [blog](https://blog.harvey-os.org) and a [twitter account](https://twitter.com/harvey_os) where we share news and stuff we are excited about.
+Welcome to Harvey, we are delighted that you are interested in the
+project.
 
+- Take a look at the
+  [Getting Started](https://github.com/Harvey-OS/harvey/wiki/Getting-Started)
+  guide to learn how to get Harvey and how to play with it.
+- You enjoyed playing with Harvey and you want to help out? Great!
+  Take a look at our
+  [Contribution Guide](https://github.com/Harvey-OS/harvey/blob/master/CONTRIBUTING.md).
+  The contribution guide covers a wide variety of topics including the
+  Harvey coding style,
+  [Code of Conduct](https://github.com/Harvey-OS/harvey/wiki/Code-of-Conduct),
+  where to get help and so on.
+- We also cover a wide variety of topics on our
+  [wiki](https://github.com/Harvey-OS/harvey/wiki) and
+  [apex's wiki](https://github.com/Harvey-OS/apex/wiki).
+- If the information you are looking for is not on the wiki, ask the
+  [Mailing list](https://groups.google.com/forum/#!forum/harvey) for
+  help. It is where most of the development conversation happens.
+- [Man Pages](https://sevki.io/harvey/sys/man/1/0intro) are where you
+  can read man pages from the head of the repository.
+- Harvey also has a [blog](https://blog.harvey-os.org) and a
+  [twitter account](https://twitter.com/harvey_os) where we share news
+  and things we are excited about.
 
 [License](https://github.com/Harvey-OS/harvey/blob/master/LICENSE.gpl)