From 201c4737d90cc6821aa5a3cce86bf5758804687a Mon Sep 17 00:00:00 2001
From: Colin Dean <git@cad.cx>
Date: Sun, 2 Jul 2017 11:42:55 -0400
Subject: [PATCH] Revises and clarifies contributing workflow

---
 CONTRIBUTING.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 45 ++++++++++------------------
 2 files changed, 94 insertions(+), 30 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e64b1a1
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,79 @@
+# Contributing to `plaintextaccounting.org`
+
+It's as easy as forking this Github repo, making your changes, and submitting a pull request.
+
+If you're a recurring contributor, [open an issue](https://github.com/plaintextaccounting/plaintextaccounting.github.io/issues/new?title=Contributor+requesting+commit+bit&body=Hello,+I+have+made+some+commits+and+would+like+to+have+commit+access.+May+I?) to request commit access if it is not granted to you. This is a human-driven process.
+
+## Dependencies
+
+This system requires a few dependencies:
+
+* [make]
+* [pandoc]
+
+[make]:   https://en.wikipedia.org/wiki/Make_(software)
+[pandoc]: http://pandoc.org/
+
+Optional, to make active development easier:
+
+* [fswatch]
+* [livereloadx]
+* [LiveReload]
+
+[fswatch]:     https://emcrisostomo.github.io/fswatch/
+[livereloadx]: https://nitoyon.github.io/livereloadx/
+[LiveReload]:  http://livereload.com/
+
+### Installation of dependencies
+
+#### macOS
+
+Using [Homebrew](https://brew.sh)
+
+For base requirements:
+
+    brew install pandoc
+
+`make` is already available when Xcode is installed.
+
+For all reloading options:
+
+    brew install fswatch npm caskroom/cask/livereload && \
+    npm install -g livereloadx
+
+## Making changes
+
+Once you've cloned the repository and setup the tools, make changes to whatever is necessary. **Don't change the `html` files**. The `html` is automatically generated!
+
+Before committing, rebuild the `html`, which requires `pandoc`):
+
+    make
+
+and include it in your commit.
+
+### Accelerating development with automated rebuilds
+
+To rebuild on each file change, which requires [fswatch]:
+
+    make watch
+
+Refresh the page in the browser manually.
+
+To rebuild _and_ reload the browser page on file change, there are two methods.
+
+**Method 1**, which requires [livereloadx]:
+
+    make watch
+
+and in another terminal:
+
+    npm install -g livereloadx
+    make livereload
+
+Then visit [`localhost:35729`](http://localhost:35729) in your browser.
+
+**Method 2**, requires [LiveReload]:
+
+1. Add the site folder in the LiveReload GUI
+2. Configure custom command `make`
+3. Edit away.
diff --git a/README.md b/README.md
index f1f46d7..38fe432 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,20 @@
-The plaintextaccounting.org website.
-An informative portal for Ledger, hledger, beancount, and the other ledger-likes.
+# The plaintextaccounting.org website.
 
-The repo is named plaintextaccounting.github.io to make it the Github
-Pages site for the plaintextaccounting organization, so that it can be
-served with a custom domain.
+plaintextaccounting.org is an informative portal for Ledger, hledger, beancount, and the other ledger-likes.
 
-Contributing
-------------
+The repo is named `plaintextaccounting.github.io` to make it the Github
+Pages site for the
+[plaintextaccounting organization](https://github.com/plaintextaccounting/),
+so that it can be served with a custom domain, `plaintextaccounting.org`.
 
-Fork the github repo, submit a pull request.
-If you're a recurring contributor, remind me to give you commit access.
+## Contributing Quick-start
 
-Before committing, rebuild the HTML (requires pandoc):
+_For full instructions on contributing, see
+[CONTRIBUTING.md](CONTRIBUTING.md)._
 
-$ make
-
-and include it in your commit.
-
-To rebuild on each file change (requires fswatch):
-
-$ make watch
-
-To rebuild and reload the browser page on file change,
-
-Method 1 (requires livereloadx):
-
-$ make watch
-in another window:
-$ npm install -g livereloadx
-$ make livereload
-visit http://localhost:35729
-
-Method 2 (requires LiveReload):
-add the site folder in the LiveReload GUI, configure custom command "make", ?
+1. Fork this repository.
+2. Make changes to the `md` files, `css`, etc. **Don't change the `html` files.**
+3. Run `make` to regenerate the `html` files.
+4. Commit.
+5. Push to a branch on your fork.
+6. Submit a pull request.