Expanded on documentation section, running through an example of committing a change to the docs end-to-end and describing the process for adding static assets (#2047)

CONTRIBUTING.md

@@ -47,9 +47,111 @@ If you are proposing a feature:
 -   Remember that this is a volunteer-driven project, and that
     contributions are welcome :)
 
-## Latest Documentation
+## Documentation
 
-Latest documentation and tutorial are available [here](http://airbnb.io/superset)
+The latest documentation and tutorial are available [here](http://airbnb.io/superset).
+
+Contributing to the official documentation is relatively easy, once you've setup
+your environment and done an edit end-to-end. The docs can be found in the
+`docs/` subdirectory of the repository, and are written in the
+[reStructuredText format](https://en.wikipedia.org/wiki/ReStructuredText) (.rst).
+If you've written Markdown before, you'll find the reStructuredText format familiar.
+
+Superset uses [Sphinx](http://www.sphinx-doc.org/en/1.5.1/) to convert the rst files
+in `docs/` to the final HTML output users see.
+
+To make changes to the rst files and build the docs using Sphinx, you'll need to install
+a handful of developer dependencies. This will likely involve installing more than you'll
+need to *just* edit the documentation, but it shouldn't take much work.
+
+First, since Superset uses the [mysqlclient](https://pypi.python.org/pypi/mysqlclient)
+package, you'll have to install some of the MySQL development files. If you're running
+Mac OS X, you can use [Homebrew](http://brew.sh/) to install these:
+
+    brew install mysql-connector-c
+
+If you're running Linux or Unix, use your package manager to install the MySQL dev
+packages, e.g. on Ubuntu:
+
+    sudo apt-get install libmysqlclient-dev
+
+Before you start changing the docs, you'll want to
+[fork the Superset project on Github](https://help.github.com/articles/fork-a-repo/).
+Once that new repository has been created, clone it on your local machine:
+
+    git clone git@github.com:your_username/superset.git
+
+At this point, you may also want to create a
+[Python virtual environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
+to manage the Python packages you're about to install:
+
+    virtualenv superset-dev
+    source superset-dev/bin/activate
+
+Finally, install the required Python dependencies by running this command
+from the root of the Superset code that you checked out above:
+
+    cd superset
+    pip install -r dev-reqs.txt
+
+To get the feel for how to edit and build the docs, let's edit a file, build
+the docs and see our changes in action. First, you'll want to
+[create a new branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
+to work on your changes:
+
+    git checkout -b changes-to-docs
+
+Now, go ahead and edit one of the files under `docs/`, say `docs/tutorial.rst`
+- change it however you want. Check out the
+[ReStructuredText Primer](http://docutils.sourceforge.net/docs/user/rst/quickstart.html)
+for a reference on the formatting of the rst files.
+
+Once you've made your changes, run this command from the root of the Superset
+repo to convert the docs into HTML:
+
+    python setup.py build_sphinx
+
+You'll see a lot of output as Sphinx handles the conversion. After it's done, the
+HTML Sphinx generated should be in `docs/_build/html`. Go ahead and navigate there
+and start a simple web server so we can check out the docs in a browser:
+
+    cd docs/_build/html
+    python -m SimpleHTTPServer
+
+This will start a small Python web server listening on port 8000. Point your
+browser to [http://localhost:8000/](http://localhost:8000/), find the file
+you edited earlier, and check out your changes!
+
+If you've made a change you'd like to contribute to the actual docs, just commit
+your code, push your new branch to Github:
+
+    git add docs/tutorial.rst
+    git commit -m 'Awesome new change to tutorial'
+    git push origin changes-to-docs
+
+Then, [open a pull request](https://help.github.com/articles/about-pull-requests/).
+
+If you're adding new images to the documentation, you'll notice that the images
+referenced in the rst, e.g.
+
+    .. image:: _static/img/tutorial/tutorial_01_sources_database.png
+
+aren't actually included in that directory. _Instead_, you'll want to add and commit
+images (and any other static assets) to the _superset/assets/images_ directory.
+When the docs are being pushed to [airbnb.io](http://airbnb.io/superset/), images
+will be moved from there to the _\_static/img_ directory, just like they're referenced
+in the docs.
+
+For example, the image referenced above actually lives in
+
+    superset/assets/images/tutorial
+
+Since the image is moved during the documentation build process, the docs reference the
+image in
+
+    _static/img/tutorial
+
+instead.
 
 ## Setting up a Python development environment