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.

5 files changed, 231 insertions, 183 deletions

diff --git a/.gitignore b/.gitignore
index 9da56bab..5f16bd74 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@ mediagoblin.egg-info
 *.pyc
 *.pyo
 docs/_build/
+docs/build
 user_dev/
 paste_local.ini
 mediagoblin_local.ini
diff --git a/docs/source/about_mediagoblin.rst b/docs/source/about_mediagoblin.rst
index af6658f3..71d8b89c 100644
--- a/docs/source/about_mediagoblin.rst
+++ b/docs/source/about_mediagoblin.rst
@@ -9,43 +9,52 @@
 What is GNU MediaGoblin
 =======================
 
-Three years ago (2008), a number of free software luminaries got
-together at the FSF office to answer the question, "What should
-software freedom look like on the participatory web?"  Those thinkers
-included Richard Stallman---founder of the free software movement and
-instigator of the GNU project, Evan Prodromou---the driving force
-behind Status.net, a highly sucessful federated micro-blogging
-service, and FIXME.
-
-Since that time Identi.ca and Libre.fm have answered the
-freedom-loving web-user's need for micro-blogging and music sharing.
-Now, GNU MediaGoblin is building a format for users to share photos.
-Later versions of MediaGoblin will include support for video and other
-media as well as tools to encourage collaboration on media projects.
-
-
-Why are we doing this?
-======================
-
-Centralization and proprietization of media on the internet is a
-serious problem and makes the web go from a system of extreme
-resilience to a system of frightening fragility.  We believe people
-should be able to free their data from proprietary control and that
-means someone has to build the tools to make it possible.  We decided
-that in this case, that someone would be us!
- 
-
-Who are you?
-============
-
-Free software activists and folks who have worked on a variety of
-other projects like Libre.fm, GNU Social, Status.net, Miro, Miro
-Community, OpenHatch and other projects as well.  We're admirers and
-contributors.  We're writers and painters.  We're friendly and
-dedicated to computer user freedom.
-
-
-How can I participate?
+In 2008 a number of free software developers and activists gathered at
+the FSF to attempt to answer the question "What should software
+freedom look like on the participatory web?" Their answer, the 
+`Franklin Street Statement <http://autonomo.us/2008/07/franklin-street-statement/>`_, 
+has lead to the development of  `autonomo.us <http://autonomo.us/>`_
+community, and  free software projects including `Identi.ca <http://identi.ca/>`_ 
+and `Libre.fm <http://libre.fm/>`_. 
+
+Identi.ca and Libre.fm address the need for micro-blogging and music
+sharing services and software that respect users' freedom and
+autonomy. GNU MediaGoblin emerges from this milieu to create a
+platform for us to share photos in an environment that respects our
+freedom and independence. In the future MediaGoblin will include
+support other media, like video, and provide tools to facilitate
+collaboration on media projects.
+
+Why Build GNU MediaGoblin
+=========================
+
+The Internet is designed--and works best--as a complex and endlessly
+resilient network. When key services and media outlets are
+concentrated in centralized platforms, the network becomes less useful
+and increasingly fragile. As always, the proprietary nature of these
+systems, hinders users ability to develop, extend, and understand
+their software; however, in the case of network services it also means
+that users must forfeit control of their data to the service
+providers. 
+
+Therefore, we believe that network services must be federated to avoid
+centralization and that everyone ought to have control over their
+data. In support of this, we've decided to help build the tools to
+make these kinds of services possible. We hope you'll join us, both as
+users and as contributors. 
+
+Who Contributes to the Project
+==============================
+
+You do! 
+
+We are free software activists and folks who have worked on a variety
+of other projects including: Libre.fm, GNU Social, Status.net, Miro,
+Miro Community, and OpenHatch among others. We're programmers,
+musicians, writers, and painters. We're friendly and dedicated to
+software and network freedom.
+
+How Can I Participate?
 ======================
 
 See `Get Involved <http://mediagoblin.org/join/>`_ on the website..
@@ -56,15 +65,15 @@ How is GNU MediaGoblin licensed?
 
 GNU MediaGoblin software is released under an AGPLv3 license.
 
-See the ``COPYING`` file in the source for details.
+See the ``COPYING`` file in the source repository for details.
 
 
-Is this an official GNU Project?  What does that mean?
-======================================================
+Is MedaGobilin an official GNU project?  What does that mean?
+=============================================================
 
-We are!  It means that we meet the GNU Project's rigourous standards
-for free software.  To find out more about what that means, check out
-`the GNU site <http://gnu.org/>`_.
+MediaGoblin is an official GNU project! This status means that we the
+meet the GNU Project's rigorous standards for free software.  To find
+out more about what that means, check out `the GNU site <http://gnu.org/>`_.
 
 Please feel free to contact us with further questions!
 
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. 
 
diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst
index 4fd96842..c525d002 100644
--- a/docs/source/foreword.rst
+++ b/docs/source/foreword.rst
@@ -1,39 +1,46 @@
-==========
- Foreword
-==========
+========
+Foreword
+========
 
-About this manual
-=================
+About the MediaGoblin Manual
+============================
 
-This is the GNU MediaGoblin manual.  This documentation targets the
-following groups of individuals:
+Welcome to the GNU MediaGoblin manual. This document targets several
+classes of users, including: 
 
-* people who want to try the software locally
-* people who want to deploy and administrate the software
+* users who would like to try the software locally, 
+* systems administrators who want to deploy and administer the
+  software in "production environments," and
+* anyone who wants to learn how MediaGoblin works. 
 
-This manual doesn't cover contributors to the codebase.  But we want
-and love contributors!  To join as a contributor please visit the
-following pages instead:
+Some information relevant to the MediaGoblin community members,
+including how to get involved (We want and love contributors!) To join
+as a contributor please see the following pages:
 
 * http://mediagoblin.org/pages/join.html for general "join us" information
 * http://wiki.mediagoblin.org/ for our contributor-focused wiki
 
-If you are viewing this from http://docs.mediagoblin.org be aware that
-this manual is a living document and is in the ``mediagoblin``
-repository in the ``docs/`` directory.
+If you suspect that documentation on http://docs.mediagoblin.org is
+out of date, it might be. The documentation is updated regularly and
+the "living" version of this resource resides in the ``mediagoblin``
+repository with the project's source code the ``docs/`` directory. 
 
+Improving the MediaGobiin Manual
+================================
 
-I found an error in the docs---who do I tell?
-=============================================
-
-There are a few ways---please pick the one most convenient to you!
+There are a few ways---please pick whichever method is convenient for
+you!
 
 1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/projects/mediagoblin/issues
 2. Tell someone on IRC ``#mediagoblin`` on Freenode.
-3. Send an email to Will ``willg at bluesock dot org``.
+3. Send an email to Will ``willg at bluesock dot org``, or Sam at
+   ``sam@cyborginstitute.com``
 
 When you tell us about your issue, please let us know:
 
 * where you are looking (in git?  url of the web-page?)
-* what the issue is
-* your thoughts on how to resolve it
+* what the issue is, and 
+* your thoughts on how to resolve it. 
+
+We hope these materials are useful and we look forward to any and all
+feedback. 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 79f2653e..93b2a942 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,7 +23,8 @@ Table of Contents:
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
+* :ref:`genindex`
+
+.. * :ref:`modindex`