First draft of readme revisions

README.md

@@ -10,41 +10,69 @@
 rstat.us is a microblogging site built on top of the [ostatus
 protocol](http://status.net/wiki/OStatus).
 
+The differences between rstat.us and other microblogging networks are *simplicity* and *openness*.
+
+*Simplicity* is a core 'feature' of rstat.us. We pride ourselves on saying 'no' to lots of features. Our interface is clean, and easy to understand. We give you just enough features to be interesting, but not enough to be complicated and confusing.
+
+*Openness* means the programming code that makes up rstat.us is available for anyone to download, free of charge. Programmers can use that code to run their own websites just like rstat.us, and you can subscribe to your friends on any site that supports the OStatus protocol, like identi.ca. This also means that you can own your data; we'll never stop you from having full access to everything you've put into rstat.us.
+
 [![Build Status](https://secure.travis-ci.org/hotsh/rstat.us.png)](http://travis-ci.org/hotsh/rstat.us)
 
+How to get help
+---------------
+
+- If you think you've found a bug, please [file a new issue](http://github.com/hotsh/rstat.us/issues) and include:
+  - What happened
+  - What you expected to happen
+  - Steps to reproduce what happened
+- You can send questions, problems, or suggestions to [the mailing list](http://librelist.com/browser/rstatus/)
+- Chat with us on IRC in #rstatus on freenode
+
 Helping out with rstat.us
 -------------------------
 
-If you'd like to contribute, here are some details:
+If you'd like to contribute, we'd love to have you! Here are some details:
 
 - The stack: ruby/rails 3.1/mongodb
 - [The code][code]
-- [The documentation][docs] (need lots of improvement here!)
+- [The documentation][docs] (We could use lots of improvement here!)
 - [The Issues list][issues]
+- Tests are written using [minitest][minitest] and [capybara][capy]
+- Documentation is generated using [docco][docco] (rocco)
 - We follow [GitHub flow][flow], as a workflow. Basically:
-  - Please fork the project and make a pull request
-    - Pull requests will not be merged without tests/documentation
-      - We use [minitest][minitest]/[capybara][capy] for tests
-      - We use [docco][docco] (rocco) for documentation
-      - If you think it doesn't need a test, make your case, I'm just saying.
+  - Please fork the project
+  - Create a feature branch
+  - Make your change, including tests and documentation as appropriate
+  - Submit a pull request from your branch
+  - A member of the core team will let you know they are looking at it as soon as they are able. We will review the code and run the tests before merging.
 
 [code]: http://github.com/hotsh/rstat.us
 [docs]: http://hotsh.github.com/rstat.us/
 [issues]: http://github.com/hotsh/rstat.us/issues
+[flow]: http://scottchacon.com/2011/08/31/github-flow.html
 [minitest]: https://github.com/seattlerb/minitest
 [capy]: https://github.com/jnicklas/capybara
 [docco]: https://github.com/jashkenas/docco
-[flow]: http://scottchacon.com/2011/08/31/github-flow.html
+
+## Development Roadmap
+
+In the first half of 2012, we plan to work on:
+- Fixing user-facing bugs or cutting buggy parts of the app
+- Fixing OStatus support
+- Implementing a RESTful API
+- Supporting and documenting running your own node
+
+Please see the [Issues](http://github.com/hotsh/rstat.us/issues), anything without an assignee is up for grabs! Don't hesitate to ask for help or clarification either on an issue itself or through one of the contact methods listed above.
 
 Source code documentation
 -------------------------
 
-We have documentation that explains all of our source code, using rocco.
+We have documentation that explains our source code using rocco.
 You can view it [here](http://hotsh.github.com/rstat.us/rstatus.html).
 
 
-Setting up a dev environment
-----------------------------
+Setting up a development environment
+------------------------------------
 
 First off: you will need MongoDB (www.mongodb.org).  They have a [quickstart
 guide][mongo-quickstart] for getting it installed and running.
@@ -62,22 +90,27 @@ And start the server:
 
     $ rails server
 
-Bam! Visit <http://localhost:9292/> in your browser, and you'll be good.
+Bam! Visit <http://localhost:3000/> in your browser, and you'll be good.
 
 To run the tests you may want to make use of `bundle exec` so you don't get
 mixed up with different versions of gems that might or might not work with
 the current rstat.us branch.
 
-Run the tests:
+Run all the tests:
+
+    $ bundle exec rake test
+
+You can run convenient subsets of the tests during development; run `bundle exec rake -T` to see all the options. You can also run one test file (for example, `test/models/author_test.rb`) by specifying the filepath in the TEST environment variable:
+
+    $ bundle exec rake test TEST=test/models/author_test.rb
 
-    $ bundle exec rake test:all
+Please run all the tests before submitting a pull request!
 
 [mongo-quickstart]: http://www.mongodb.org/display/DOCS/Quickstart
 
 Running your own node
 ---------------------
 
-If you need help with this, then you're not ready to run one. We're working
-on making this super easy, but right now, we're not quite there.
+We're working on making this super easy, but right now, we're not quite there.
 
 If you do run your own node, please keep current with upstream.