heckyel/mediagoblin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation Revision, clarification, and editing.

Browse Source 
- 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.
This commit is contained in:
tycho garen 2011-08-27 17:43:14 -04:00
parent 7d6a9058dd
commit 6503d66c98
5 changed files with 224 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -9,6 +9,7 @@ mediagoblin.egg-info
*.pyc *.pyc
*.pyo *.pyo
docs/_build/ docs/_build/
docs/build
user_dev/ user_dev/
paste_local.ini paste_local.ini
mediagoblin_local.ini mediagoblin_local.ini

79
docs/source/about_mediagoblin.rst
View File

@ -9,43 +9,52 @@
What is GNU MediaGoblin What is GNU MediaGoblin
======================= =======================
Three years ago (2008), a number of free software luminaries got In 2008 a number of free software developers and activists gathered at
together at the FSF office to answer the question, "What should the FSF to attempt to answer the question "What should software
software freedom look like on the participatory web?" Those thinkers freedom look like on the participatory web?" Their answer, the
included Richard Stallman---founder of the free software movement and `Franklin Street Statement <http://autonomo.us/2008/07/franklin-street-statement/>`_,
instigator of the GNU project, Evan Prodromou---the driving force has lead to the development of `autonomo.us <http://autonomo.us/>`_
behind Status.net, a highly sucessful federated micro-blogging community, and free software projects including `Identi.ca <http://identi.ca/>`_
service, and FIXME. and `Libre.fm <http://libre.fm/>`_.
Since that time Identi.ca and Libre.fm have answered the Identi.ca and Libre.fm address the need for micro-blogging and music
freedom-loving web-user's need for micro-blogging and music sharing. sharing services and software that respect users' freedom and
Now, GNU MediaGoblin is building a format for users to share photos. autonomy. GNU MediaGoblin emerges from this milieu to create a
Later versions of MediaGoblin will include support for video and other platform for us to share photos in an environment that respects our
media as well as tools to encourage collaboration on media projects. 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
=========================
Why are we doing this? 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.
Centralization and proprietization of media on the internet is a Therefore, we believe that network services must be federated to avoid
serious problem and makes the web go from a system of extreme centralization and that everyone ought to have control over their
resilience to a system of frightening fragility. We believe people data. In support of this, we've decided to help build the tools to
should be able to free their data from proprietary control and that make these kinds of services possible. We hope you'll join us, both as
means someone has to build the tools to make it possible. We decided users and as contributors.
that in this case, that someone would be us!
Who Contributes to the Project
==============================
Who are you? You do!
============
Free software activists and folks who have worked on a variety of We are free software activists and folks who have worked on a variety
other projects like Libre.fm, GNU Social, Status.net, Miro, Miro of other projects including: Libre.fm, GNU Social, Status.net, Miro,
Community, OpenHatch and other projects as well. We're admirers and Miro Community, and OpenHatch among others. We're programmers,
contributors. We're writers and painters. We're friendly and musicians, writers, and painters. We're friendly and dedicated to
dedicated to computer user freedom. software and network freedom.
How Can I Participate?
How can I participate?
====================== ======================
See `Get Involved <http://mediagoblin.org/join/>`_ on the website.. 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. 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 MediaGoblin is an official GNU project! This status means that we the
for free software. To find out more about what that means, check out meet the GNU Project's rigorous standards for free software. To find
`the GNU site <http://gnu.org/>`_. out more about what that means, check out `the GNU site <http://gnu.org/>`_.
Please feel free to contact us with further questions! Please feel free to contact us with further questions!

230
docs/source/contributinghowto.rst
View File

@ -1,84 +1,97 @@
.. _contributing-howto-chapter: .. _contributing-howto-chapter:
==================== ===================================
Contributing HOWTO HOWTO Contribute to GNU MediaGoblin
==================== ===================================
.. contents:: Sections .. contents:: Sections
:local: :local:
.. _join-the-community-section: .. _join-the-community-section:
Join the community! Join the community!
=================== ===================
We're super glad you want to join our community! We're **really** glad that you want to join the MediaGoblin community!
See `the join page on the website <http://mediagoblin.org/join/>`_ for There are a variety of ways to help and support MediaGoblin and to
where we hang out. 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.
There are a variety of ways you can help us and become part of the This document provides an overview of different ways you can get
team. We're not just looking for coders! We're also looking for involved with MediaGoblin along with instructions for getting
documentation writers, users, testers, evangelists, user-interface started. There is some obvious overlap with `the "join" page on
designers, graphics designers, user-experience designers, system mediagoblin.org <http://mediagoblin.org/pages/join.html>`_ at present.
administrators, friends, painters, bakers, candle-stick makers...
Here are some things you can do today: Hang out with the MediaGoblin folk
----------------------------------
MediaGoblin has a `discussion listserv <http://lists.mediagoblin.org/listinfo/devel>`_,
and an IRC (``#mediagoblin``) channel on `freenode.net <http://freenode.com>`_.
**Hang out with us** 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.
You should hang out with us! We like people like you! File Bugs / Triage Bugs
-----------------------
At a bare minimum, join the `mailing list Issue reports are critical for all projects. Identified bugs give
<http://mediagoblin.org/join/>`_ and say, "Hi!" 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.
We also hang out on IRC in ``#mediagoblin`` on Freenode.net. See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best
and most useful bug reports.
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.
**File bugs** See the section on `bug triage <#triage-bugs>`_ for suggestions on how
to most effectively triage and approach the issue queue.
Filing bugs is a critical part of any project. For more Write/Fix Code
information on filing bugs, see :ref:`filing-bugs`. --------------
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!
**Write/Fix some code** Send Encouragement, Spread the Word
-----------------------------------
If you are a coder and you're looking to code, check out the Sometimes, a nice word, simple encouragement, and interest in the work
`wiki <http://wiki.mediagoblin.org/`_. We even have tips on we're doing is enough to inspire a tizzy of productive work. Just a
*becoming* a coder and we're willing to help you! 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.
**Send encouragement** 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.
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 it to the `mailing list <http://mediagoblin.org/join/>`_
or hop into ``#mediagoblin`` on Freenode.net and let us know.
**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?
Participate in MediaGoblin
==========================
We're still working on project infrastructure. We hope to have the 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: bits in place for these additional things to do in the coming months:
**Become a user** Become a User
-------------
We're building GNU MediaGoblin for us and for you but really 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 you're one of us and I am you and we are we and GNU
@ -89,7 +102,8 @@ bits in place for these additional things to do in the coming months:
and you can salt and pepper it to your liking. and you can salt and pepper it to your liking.
**Help other users** Help Others
-----------
Have you spent time with GNU MediaGoblin? If so, your Have you spent time with GNU MediaGoblin? If so, your
experience and wisdom are invaluable and you're the best experience and wisdom are invaluable and you're the best
@ -97,7 +111,8 @@ bits in place for these additional things to do in the coming months:
questions. questions.
**Run your own instance** Run your own MediaGoblin Instance
---------------------------------
Are there things about our instance you want to change? Are Are there things about our instance you want to change? Are
there things about other instances you wish were different? there things about other instances you wish were different?
@ -106,80 +121,95 @@ bits in place for these additional things to do in the coming months:
own instance! own instance!
For more information on deploying your own instance, see For more information on deploying your own instance, see
:ref:`deployment-howto`. the `Deployment HOWTO </deploymenthowto.html>`_
.. _translating:
**Translate GNU MediaGoblin** Translate MediaGoblin
---------------------
Knowing more than one language is an important skill. If you If you know English and another language and feel comfortable
are multi-lingual and are interested in translating GNU translating elements of the interface or even the documentation,
MediaGoblin, see :ref:`translating`. we'd love to have help translating the software and resources.
Create a Theme
--------------
**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
As people deploy their own GNU MediaGoblin instances, good design or theming background, consider developing themes for
themes are a must have! For more information on theming, see MediaGoblin. New themes help test the theming system, provide
:ref:`theming-howto`. 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
Contributing thank you drawings / copyright assignment information.
======================================================
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.
For why we're doing copyright assignment, see the
`wiki <http://wiki.mediagoblin.org/>`_.
.. _filing-bugs: .. _filing-bugs:
File bugs File Bugs
========= =========
GNU MediaGoblin uses a bug tracker called `Redmine MediaGoblin uses a bug tracker called `Redmine <http://www.redmine.org>`_.
<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. 1. A short summary that's 60 characters or less.
2. A description that describes the issue (bug, feature request, ...) 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 * If you think you've found a bug, can you reproduce it in a
browser, computer, image, ...? 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 * If you're submitting a feature request, are there related links
for more information? Would you be willing to help implement or on the Internet for more information? Would you be willing to
test the feature? help implement or test the feature?
That's it! When someone looks into the issue and has questions, That's it!
they'll contact you!
If you don't hear from anyone in a couple of weeks, find someone on The better the issue report, the easier it is to address the bug, and
IRC. 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:
Translate GNU MediaGoblin Triage Bugs
========================= ===========
Coming soon when we set up translation infrastructure. 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:
Where to go when you get stuck - ensure that one or two people in addition to the initial reporter
============================== have been able to reproduce the issue.
Go to `our Web site <http://mediagoblin.org/>`_ where we list the - document the issue more clearly. If you had any trouble reproducing
various places we hang out and how to get a hold of us. 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.
How to Get Help with MediaGoblin
================================
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.

49
docs/source/foreword.rst
View File

@ -1,39 +1,46 @@
========== ========
Foreword Foreword
========== ========
About this manual About the MediaGoblin Manual
================= ============================
This is the GNU MediaGoblin manual. This documentation targets the Welcome to the GNU MediaGoblin manual. This document targets several
following groups of individuals: classes of users, including:
* people who want to try the software locally * users who would like to try the software locally,
* people who want to deploy and administrate the software * 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 Some information relevant to the MediaGoblin community members,
and love contributors! To join as a contributor please visit the including how to get involved (We want and love contributors!) To join
following pages instead: as a contributor please see the following pages:
* http://mediagoblin.org/pages/join.html for general "join us" information * http://mediagoblin.org/pages/join.html for general "join us" information
* http://wiki.mediagoblin.org/ for our contributor-focused wiki * http://wiki.mediagoblin.org/ for our contributor-focused wiki
If you are viewing this from http://docs.mediagoblin.org be aware that If you suspect that documentation on http://docs.mediagoblin.org is
this manual is a living document and is in the ``mediagoblin`` out of date, it might be. The documentation is updated regularly and
repository in the ``docs/`` directory. 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 whichever method is convenient for
============================================= you!
There are a few ways---please pick the one most convenient to you!
1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/projects/mediagoblin/issues 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. 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: When you tell us about your issue, please let us know:
* where you are looking (in git? url of the web-page?) * where you are looking (in git? url of the web-page?)
* what the issue is * what the issue is, and
* your thoughts on how to resolve it * your thoughts on how to resolve it.
We hope these materials are useful and we look forward to any and all
feedback.

5
docs/source/index.rst
View File

@ -23,7 +23,8 @@ Table of Contents:
Indices and tables Indices and tables
================== ==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search` * :ref:`search`
* :ref:`genindex`
.. * :ref:`modindex`