aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorWill Kahn-Greene <willg@bluesock.org>2011-04-27 22:42:17 -0400
committerWill Kahn-Greene <willg@bluesock.org>2011-04-27 22:46:27 -0400
commit9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba (patch)
treeb6be68c4d65a379fdeb78d8bdd034b3ebd4c00b0 /docs
parent84489d7d4a3b3c0a897a9c4fe5176484bcf31d82 (diff)
downloadmediagoblin-9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba.tar.lz
mediagoblin-9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba.tar.xz
mediagoblin-9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba.zip
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.
Diffstat (limited to 'docs')
-rw-r--r--docs/beardomatic.rst2
-rw-r--r--docs/contributinghowto.rst115
-rw-r--r--docs/deploymenthowto.rst2
-rw-r--r--docs/foreward.rst7
-rw-r--r--docs/hackinghowto.rst61
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.