Reworked contributing docs based on Asheesh's thoughts

I chatted with Asheesh on IRC today and asked him to look over the
contributer howto.  He had a lot of thoughts and I factored most/all
of them in.  It's much better now.

5 files changed, 139 insertions, 48 deletions

diff --git a/docs/beardomatic.rst b/docs/beardomatic.rst
index 5ebeb239..14130f6a 100644
--- a/docs/beardomatic.rst
+++ b/docs/beardomatic.rst
@@ -1,3 +1,5 @@
+.. _beardomatic-chapter:
+
 ===========================================
  Beardomatic: Infrastructure Documentation
 ===========================================
diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst
index cb5cd909..3b3fe163 100644
--- a/docs/contributinghowto.rst
+++ b/docs/contributinghowto.rst
@@ -2,72 +2,104 @@
  Contributing HOWTO
 ====================
 
-We're super glad you want to contribute!
+Join the community!
+===================
+
+We're super glad you want to join our community!
 
 There are a variety of ways you can help us and become part of the
 team.  We're not just looking for coders!  We're also looking for
-documentation writers, users, testers, evangelists, painters, bakers,
-candle-stick makers...
+documentation writers, users, testers, evangelists, user-interface
+designers, graphics designers, user-experience designers, system
+administrators, friends, painters, bakers, candle-stick makers...
 
-However, if you are a coder and you're looking to code, check out the
-:ref:`hacking-howto`.
+Here are some things you can do today:
 
-The rest of this chapter talks about different things we need your
-help with.
 
+    **Hang out with us**
 
-**Become a user**
+        You should hang out with us!  We like people like you!
 
-    We're building GNU MediaGoblin for us and for you but really
-    you're one of us and I am you and we are we and GNU MediaGoblin is
-    the walrus.
-    
-    Sign up for an account.  Use the service.  Relish in the thought
-    that this service comes with a heaping side of Freedom and you can
-    salt and pepper it to your liking.
+        At a bare minimum, join the `mailing list
+        <http://mediagoblin.org/join/>`_ and say, "Hi!"
 
+        We also hang out on IRC in ``#mediagoblin`` on Freenode.net.
 
-**File bugs**
 
-    Filing bugs is a critical part of any project.  For more
-    information on filing bugs, see :ref:`filing-bugs`.
+    **File bugs**
 
+        Filing bugs is a critical part of any project.  For more
+        information on filing bugs, see :ref:`filing-bugs`.
 
-**Translate GNU MediaGoblin**
 
-    Knowing more than one language is an important skill.  If you are
-    multi-lingual and are interested in translating GNU MediaGoblin,
-    see :ref:`translating`.
+    **Write/Fix some code**
 
+        If you are a coder and you're looking to code, check out the
+        :ref:`hacking-howto`.  We even have tips on *becoming* a coder
+        and we're willing to help you!
 
-**Create a theme**
 
-    As people deploy their own GNU MediaGoblin instances, good themes
-    are a must have!  For more information on theming, see
-    :ref:`theming-howto`.
+    **Run your own instance**
+
+        Are there things about our instance you want to change?  Are
+        there things about other instances you wish were different?
+        Want to test upcoming changes?  Want to create patches to
+        implement things you need?  That's great---you can run your
+        own instance!
+    
+        For more information on deploying your own instance, see
+        :ref:`deployment-howto`.
 
 
-**Spread the word**
+    **Spread the word**
 
-    The seductive call of Free Software services is a powerful one,
-    but many cannot hear it because it'd drowned out by the rush hour
-    traffic honking of proprietary walled gardens and faux free
-    services.  Yuck!  Be the sweet chirrup of the bird amidst the din!
-    Tell others that there is a better way to live!
+        The seductive call of Free Software services is a powerful
+        one, but many cannot hear it because it'd drowned out by the
+        rush hour traffic honking of proprietary walled gardens and
+        faux free services.  Yuck!  Be the sweet chirrup of the bird
+        amidst the din!  Tell others that there is a better way to
+        live!
 
-    FIXME - do we want to talk about ways to spread the word?
+        FIXME - do we want to talk about ways to spread the word?
 
-    FIXME - how can people notify us that they're spreading the word?
+        FIXME - how can people notify us that they're spreading the
+        word?
 
 
-**Run your own instance**
+We're still working on project infrastructure.  We hope to have the
+bits in place for these additional things to do in the coming months:
 
-    Are there things about our instance you want to change?  Are there
-    things about other instances you wish were different?  That's
-    great---you can run your own instance!
+    **Become a user**
+
+        We're building GNU MediaGoblin for us and for you but really
+        you're one of us and I am you and we are we and GNU
+        MediaGoblin is the walrus.
     
-    For more information on deploying your own instance, see
-    :ref:`deployment-howto`.
+        Sign up for an account.  Use the service.  Relish in the
+        thought that this service comes with a heaping side of Freedom
+        and you can salt and pepper it to your liking.
+
+
+    **Help other users**
+
+        Have you spent time with GNU MediaGoblin?  If so, your
+        experience and wisdom are invaluable and you're the best
+        person we can think of to help other users with their
+        questions.
+
+
+    **Translate GNU MediaGoblin**
+
+        Knowing more than one language is an important skill.  If you
+        are multi-lingual and are interested in translating GNU
+        MediaGoblin, see :ref:`translating`.
+
+
+    **Create a theme**
+
+        As people deploy their own GNU MediaGoblin instances, good
+        themes are a must have!  For more information on theming, see
+        :ref:`theming-howto`.
 
 
 Contributing thank you drawings / copyright assignment
@@ -93,8 +125,7 @@ File bugs
 GNU MediaGoblin uses a bug tracker called `Redmine
 <http://www.redmine.org>`_.
 
-The bug tracker is at http://bugs.foocorp.net/ and bugs go in the
-``GNU mediagoblin`` project.
+The bug tracker is at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
 
 A good bug report has the following things in it:
 
diff --git a/docs/deploymenthowto.rst b/docs/deploymenthowto.rst
index 684ac1b1..d943e276 100644
--- a/docs/deploymenthowto.rst
+++ b/docs/deploymenthowto.rst
@@ -9,3 +9,5 @@ Step 1: Write code that can be deployed.
 Step 2: ?
 
 Step 3: Write the deployment guide and profit!
+
+But seriously, this is a stub since we're not quite there, yet.
diff --git a/docs/foreward.rst b/docs/foreward.rst
index edc75e30..d2b9c417 100644
--- a/docs/foreward.rst
+++ b/docs/foreward.rst
@@ -27,6 +27,7 @@ In no particular order:
 * Greg
 * Karen
 * Matt
+* Asheesh
 
 
 I found an error in the docs---who do I tell?
@@ -34,9 +35,9 @@ I found an error in the docs---who do I tell?
 
 There are a few ways---please pick the one most convenient to you!
 
-1. Send an email to Will ``willg at bluesock dot org``.
-2. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ .
-3. Tell someone on IRC ``#mediagoblin`` on Freenode.
+1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ .
+2. Tell someone on IRC ``#mediagoblin`` on Freenode.
+3. Send an email to Will ``willg at bluesock dot org``.
 
 When you tell us about your issue, please let us know:
 
diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst
index 50c59d08..8b40e37d 100644
--- a/docs/hackinghowto.rst
+++ b/docs/hackinghowto.rst
@@ -8,8 +8,9 @@
 So you want to hack on GNU MediaGoblin?
 =======================================
 
-First thing to do is check out the Web site where we list all the
-project infrastructure including:
+First thing to do is check out the `Web site
+<http://mediagoblin.org>`_ where we list all the project
+infrastructure including:
 
 * the mailing list
 * the IRC channel
@@ -87,6 +88,13 @@ update your development environment.  To do that, run::
 Wiping your environment for a clean-slate
 -----------------------------------------
 
+.. Note::
+
+   Unless you're doing development and working on and testing creating
+   a new instance, you will probably never have to do this.  Will
+   plans to do this work and thus he documented it.
+
+
 Delete the following directories:
 
 * bin/
@@ -96,7 +104,8 @@ Delete the following directories:
 * parts/
 * user_dev/
 
-FIXME - how to drop data from mongodb?
+FIXME - how to drop data from mongodb?  we should probably write a
+script.
 
 
 Running the server
@@ -151,3 +160,49 @@ Bite-sized bugs to start with
 =============================
 
 FIXME - write this
+
+
+Tips for people new to coding
+=============================
+
+Python
+------
+
+GNU MediaGoblin is written using a programming language called `Python
+<http://python.org/>`_.
+
+There are two different incompatible iterations of Python which I'll
+refer to as Python 2 and Python 3.  GNU MediaGoblin is written in
+Python 2 and requires Python 2.6 or 2.7.  At some point, we might
+switch to Python 3, but that's a future thing.
+
+You can learn how to code in Python 2 from several excellent books
+that are freely available on the Internet:
+
+* `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_
+* `Dive Into Pyton <http://diveintopython.org/>`_
+* `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_
+* `A Byte of Python <http://www.swaroopch.com/notes/Python>`_
+
+These are all excellent texts.
+
+FIXME - are there good quality Python tutorial videos?
+
+
+Libraries
+---------
+
+GNU MediaGoblin uses a variety of libraries in order to do what it
+does.  These libraries are listed in the :ref:`beardomatic-chapter`
+along with links to the project Web sites and documentation for the
+libraries.
+
+There are a variety of Python-related conferences every year that have
+sessions covering many aspects of these libraries.  You can find them
+at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_.
+
+.. [0] This is a shameless plug.  Will Kahn-Greene runs Python Miro
+   Community.
+
+If you have questions or need help, find us on the mailing list and on
+IRC.