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
*.pyo
docs/_build/
docs/build
user_dev/
paste_local.ini
mediagoblin_local.ini

79
docs/source/about_mediagoblin.rst
View File

@ -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.
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/>`_.
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.
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
=========================
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
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!
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
==============================
Who are you?
============
You do!
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.
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?
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!

230
docs/source/contributinghowto.rst
View File

@ -1,84 +1,97 @@
.. _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!
We're **really** glad that you want to join the MediaGoblin community!
See `the join page on the website <http://mediagoblin.org/join/>`_ for
where we hang out.
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.
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...
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.
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
<http://mediagoblin.org/join/>`_ and say, "Hi!"
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.
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
information on filing bugs, see :ref:`filing-bugs`.
Write/Fix Code
--------------
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
`wiki <http://wiki.mediagoblin.org/`_. We even have tips on
*becoming* a coder and we're willing to help you!
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.
**Send encouragement**
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?
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**
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
@ -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.
**Help other users**
Help Others
-----------
Have you spent time with GNU MediaGoblin? If so, your
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.
**Run your own instance**
Run your own MediaGoblin Instance
---------------------------------
Are there things about our instance you want to change? Are
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!
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
are multi-lingual and are interested in translating GNU
MediaGoblin, see :ref:`translating`.
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.
Create a Theme
--------------
**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
======================================================
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/>`_.
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:
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
various places we hang out and how to get a hold of us.
- 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.
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
==========
========
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.

5
docs/source/index.rst
View File

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