From 6503d66c98765802836b09fb9f6a5f2ad47ad47a Mon Sep 17 00:00:00 2001 From: tycho garen Date: Sat, 27 Aug 2011 17:43:14 -0400 Subject: [PATCH] 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. --- .gitignore | 1 + docs/source/about_mediagoblin.rst | 95 ++++++----- docs/source/contributinghowto.rst | 262 +++++++++++++++++------------- docs/source/foreword.rst | 51 +++--- docs/source/index.rst | 5 +- 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 `_, +has lead to the development of `autonomo.us `_ +community, and free software projects including `Identi.ca `_ +and `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 `_ 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 `_. +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 `_. 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 `_ 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 `_ at present. - At a bare minimum, join the `mailing list - `_ 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 `_, +and an IRC (``#mediagoblin``) channel on `freenode.net `_. +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 `_ +as a starting point. - If you are a coder and you're looking to code, check out the - `wiki `_ 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 `_ +is hosted on `gitorious `_. 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 `_ 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 `_ - 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 `_ +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 `_ +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 `_ +.. _translating: -Contributing thank you drawings / copyright assignment -====================================================== +Translate MediaGoblin +--------------------- -Copyright assignment with GNU MediaGoblin to the `FSF -`_ 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 `_. +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 -`_. +MediaGoblin uses a bug tracker called `Redmine `_. -The bug tracker is at ``_. +Our instance is located at ``_. -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 `_ +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 `_ 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 `_ +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` -- 2.25.1