Documentation Revision, clarification, and editing.

- a line in the .gitignore file to ignore the built documentation
  tree.

- a complete revision/editorial pass of all non-technical documents
  that outline process, project fundamentals, and background. These
  edits clarified the text, unified the style, and elaborated on
  stubs.

1 files changed, 146 insertions, 116 deletions

diff --git a/docs/source/contributinghowto.rst b/docs/source/contributinghowto.rst
index a4f5771a..8eaff5e4 100644
--- a/docs/source/contributinghowto.rst
+++ b/docs/source/contributinghowto.rst
@@ -1,185 +1,215 @@
 .. _contributing-howto-chapter:
 
-====================
- Contributing HOWTO
-====================
+===================================
+HOWTO Contribute to GNU MediaGoblin
+===================================
 
 .. contents:: Sections
    :local:
 
-
 .. _join-the-community-section:
 
 Join the community!
 ===================
 
-We're super glad you want to join our community!
-
-See `the join page on the website <http://mediagoblin.org/join/>`_ for
-where we hang out.
-
-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, user-interface
-designers, graphics designers, user-experience designers, system
-administrators, friends, painters, bakers, candle-stick makers...
-
-Here are some things you can do today:
-
+We're **really** glad that you want to join the MediaGoblin community!
 
-    **Hang out with us**
+There are a variety of ways to help and support MediaGoblin and to
+join the team.  If you want to code, great, if not, even better!
+MediaGoblin interested contributors in many different roles: users,
+system administrators, technical writers, testers, evangelists,
+UI/UX and graphics designers, cheerleaders, and dreamers. 
 
-        You should hang out with us!  We like people like you!
+This document provides an overview of different ways you can get
+involved with MediaGoblin along with instructions for getting
+started. There is some obvious overlap with `the "join" page on
+mediagoblin.org <http://mediagoblin.org/pages/join.html>`_ at present.
 
-        At a bare minimum, join the `mailing list
-        <http://mediagoblin.org/join/>`_ and say, "Hi!"
+Hang out with the MediaGoblin folk
+----------------------------------
 
-        We also hang out on IRC in ``#mediagoblin`` on Freenode.net.
+MediaGoblin has a `discussion listserv <http://lists.mediagoblin.org/listinfo/devel>`_, 
+and an IRC (``#mediagoblin``) channel on `freenode.net <http://freenode.com>`_.
 
+Don't be afraid to drop by and say "Hi!" And, if you're looking for
+something to do, just ask: there's always work to be done. 
 
-    **File bugs**
+File Bugs / Triage Bugs
+-----------------------
 
-        Filing bugs is a critical part of any project.  For more
-        information on filing bugs, see :ref:`filing-bugs`.
+Issue reports are critical for all projects. Identified bugs give
+developers a basis for beginning work, and providing an idea of what
+features and issues are most important to users and the overall
+usability of the software. If you identify errors, flaws, unexpected
+behaviors, or deficits that impede use, file a bug. 
 
+See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best
+and most useful bug reports. 
 
-    **Write/Fix some code**
+If you want to contribute to MediaGoblin and don't know where to
+start, look at the `bug database <http://bugs.foocorp.net/projects/mediagoblin/issues>`_
+as a starting point. 
 
-        If you are a coder and you're looking to code, check out the
-        `wiki <http://wiki.mediagoblin.org/`_.  We even have tips on 
-        *becoming* a coder and we're willing to help you!
+See the section on `bug triage <#triage-bugs>`_ for suggestions on how
+to most effectively triage and approach the issue queue.
 
+Write/Fix Code
+--------------
 
-    **Send encouragement**
+If you are a coder and you would like to write code, the `repository <https://gitorious.org/mediagoblin>`_ 
+is hosted on `gitorious <https://gitorious.org/>`_. Clone or fork the
+repository and start poking around. Become familiar with this `manual </>`_ 
+for an overview of how the software works and is used. Consider the
+`contributor wiki <http://wiki.mediagoblin.org/>`_ for more
+information about the project, our preferred methods, and guides for
+developing MediaGoblin. We even have tips on *becoming* a coder and
+we're willing to help!
 
-        A nice word from you could send someone into a tizzy of
-        productive work.  Ten nice words could complete a feature.
-        One hundred nice words could get us to the next milestone.
+Send Encouragement, Spread the Word
+-----------------------------------
 
-        Send it to the `mailing list <http://mediagoblin.org/join/>`_
-        or hop into ``#mediagoblin`` on Freenode.net and let us know.
+Sometimes, a nice word, simple encouragement, and interest in the work
+we're doing is enough to inspire a tizzy of productive work. Just a
+bit more interest and encouragement can even make the difference
+between a complete feature and limited functionality; between a
+completed milestone and lost momentum. 
 
+Similarly, MediaGoblin, and the movement for free network services, is
+always in need of encouragement. Use free network services, understand
+the `principals <http://autonomo.us/2008/07/franklin-street-statement/>`_ 
+behind the movement, be able to articulate the benefits of free
+network services and the problems with psudo-free applications that
+don't respect the users' freedom. 
 
-    **Spread the word**
-
-        The seductive call of Free Software services is a powerful
-        one, but many cannot hear it because it's 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 - how can people notify us that they're spreading the
-        word?
+Write a blog post, post a status update, drop by the `listserv <http://mediagoblin.org/join/>`_
+or join ``#mediagoblin`` on freenode.net and let us know.
 
+Participate in MediaGoblin
+==========================
 
 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:
 
-    **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.
-    
-        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.
+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.
 
-    **Help other users**
+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.
 
-        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.
 
+Help Others
+-----------
 
-    **Run your own instance**
+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.
 
-        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`.
 
+Run your own MediaGoblin Instance
+---------------------------------
 
-    **Translate GNU MediaGoblin**
+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!
 
-        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`.
+For more information on deploying your own instance, see
+the `Deployment HOWTO </deploymenthowto.html>`_ 
 
+.. _translating:
 
-Contributing thank you drawings / copyright assignment
-======================================================
+Translate MediaGoblin
+---------------------
 
-Copyright assignment with GNU MediaGoblin to the `FSF
-<http://fsf.org>`_ is highly encouraged but not mandatory.  To
-incentivize both this and people to make cool contributions to our
-project, if you make useful contributions to GNU MediaGoblin *and* do
-a copyright assignment to the Free Software Foundation, the founder of
-the project, Chris Webber, will make a custom drawing of a goblin
-dedicated specifically to you.
+If you know English and another language and feel comfortable
+translating elements of the interface or even the documentation,
+we'd love to have help translating the software and resources. 
 
-For why we're doing copyright assignment, see the
-`wiki <http://wiki.mediagoblin.org/>`_.
+Create a Theme
+--------------
 
+MedaGoblin development is premised on the idea that the entire
+interface for the platform be completely theme-able. If you have a
+design or theming background, consider developing themes for
+MediaGoblin. New themes help test the theming system, provide
+attractive and appealing interfaces for prospective users. If you want
+to start a new theme but don't know where to start, touch base with
+the development community on the list or in the IRC channel for more
+information.
 
 .. _filing-bugs:
 
-File bugs
+File Bugs
 =========
 
-GNU MediaGoblin uses a bug tracker called `Redmine
-<http://www.redmine.org>`_.
+MediaGoblin uses a bug tracker called `Redmine <http://www.redmine.org>`_.
 
-The bug tracker is at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
+Our instance is located at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
 
-A good bug report has the following things in it:
+The most useful bug reports have the following components: 
 
 1. A short summary that's 60 characters or less.
 
 2. A description that describes the issue (bug, feature request, ...)
-   as well as the context.
+   as well as the context. Consider: 
 
-  * If it's a bug, can you reproduce it?  Is the issue specific to a
-    browser, computer, image, ...?
+   * If you think you've found a bug, can you reproduce it in a
+     controlled environment?  Is the issue specific to a browser,
+     computer, image, media type, or other dimension? All data helps. 
 
-  * If it's a feature request, are there related links on the Internet
-    for more information?  Would you be willing to help implement or
-    test the feature?
+   * If you're submitting a feature request, are there related links
+     on the Internet for more information?  Would you be willing to
+     help implement or test the feature?
 
-That's it!  When someone looks into the issue and has questions,
-they'll contact you!
+That's it! 
 
-If you don't hear from anyone in a couple of weeks, find someone on
-IRC.
+The better the issue report, the easier it is to address the bug, and
+the more likely that the developers will be able to resolve the
+issue. If someone has questions about the bug report, they may reach
+out to the reporter directly. 
 
+If you get a response after a couple of weeks, find someone on IRC.
 
-.. _translating:
+.. _triage-bugs:
+
+Triage Bugs
+===========
+
+The triage process involves reviewing bugs, removing duplicates,
+validating that the issues described are reproducible, ensuring that
+the exact behavior is properly documented, diagnosing the cause of
+each issue, and working with developers to ensure that critical bugs
+get addressed. In many cases, developers do this kind of work as a
+matter of course, but one need not be able to code in order to help
+working with bugs.
+
+To triage bugs, go to the `bug tracker <http://bugs.foocorp.net/projects/mediagoblin>`_ 
+and begin reviewing the open issues. If you are able, attempt to: 
 
-Translate GNU MediaGoblin
-=========================
+- ensure that one or two people in addition to the initial reporter
+  have been able to reproduce the issue. 
 
-Coming soon when we set up translation infrastructure.
+- document the issue more clearly. If you had any trouble reproducing
+  the issue, provide any elucidating information that you can to help
+  others solve the problem more effectively.
+  
+- find a way to resolve the problem or provide a workaround.
 
+For help, instructions, and suggestions be in touch with the
+development community on the list or in the IRC channel for more
+information. With many eyes, all bugs are shallow. 
 
-Where to go when you get stuck
-==============================
+How to Get Help with MediaGoblin
+================================
 
-Go to `our Web site <http://mediagoblin.org/>`_ where we list the
-various places we hang out and how to get a hold of us.
+The usual channels, the IRC channel, the listserv, the bug tracker,
+are all great ways to be in touch with us. Check the `web site <http://mediagoblin.org/pages/join.html>`_
+for more specific contact information.