From 917d4663afedded7e6606b1a799771da8dc2a37c Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 5 Oct 2011 23:08:53 -0400 Subject: Overhauls docs * Removes a bunch of content that doesn't need to be in the suer manual anymore. * Fixes issues so it's more readable in source form. * Adds help chapter. * Moves links out of paragraphs to reduce line length. * Cleans up some language. * Fixes some links. --- docs/source/about.rst | 88 ++++++++++++++++ docs/source/about_mediagoblin.rst | 79 -------------- docs/source/codebase.rst | 21 ++-- docs/source/contributinghowto.rst | 215 -------------------------------------- docs/source/deploying.rst | 16 +++ docs/source/deploymenthowto.rst | 16 --- docs/source/foreword.rst | 37 +++---- docs/source/help.rst | 16 +++ docs/source/index.rst | 9 +- docs/source/theming.rst | 8 ++ docs/source/theminghowto.rst | 8 -- docs/source/vision.rst | 142 ------------------------- 12 files changed, 152 insertions(+), 503 deletions(-) create mode 100644 docs/source/about.rst delete mode 100644 docs/source/about_mediagoblin.rst delete mode 100644 docs/source/contributinghowto.rst create mode 100644 docs/source/deploying.rst delete mode 100644 docs/source/deploymenthowto.rst create mode 100644 docs/source/help.rst create mode 100644 docs/source/theming.rst delete mode 100644 docs/source/theminghowto.rst delete mode 100644 docs/source/vision.rst (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 00000000..1a2df809 --- /dev/null +++ b/docs/source/about.rst @@ -0,0 +1,88 @@ +======================= + About GNU MediaGoblin +======================= + +.. contents:: Sections + :local: + + +What is GNU MediaGoblin +======================= + +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`_. + +.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/ +.. _autonomo.us: http://autonomo.us/ +.. _identi.ca: http://identi.ca/ +.. _Libre.fm: http://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. We +eagerly look forward to seeing you! + + +How is GNU MediaGoblin licensed? +================================ + +GNU MediaGoblin software is released under an AGPLv3 license. + +See the ``COPYING`` file in the root of the source for details. + + +Is MedaGobilin an official GNU project? What does that mean? +============================================================= + +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 website`_. + +Please feel free to contact us with further questions! + +.. _GNU website: http://gnu.org/ diff --git a/docs/source/about_mediagoblin.rst b/docs/source/about_mediagoblin.rst deleted file mode 100644 index 71d8b89c..00000000 --- a/docs/source/about_mediagoblin.rst +++ /dev/null @@ -1,79 +0,0 @@ -================= - GNU MediaGoblin -================= - -.. contents:: Sections - :local: - - -What is GNU MediaGoblin -======================= - -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.. - - -How is GNU MediaGoblin licensed? -================================ - -GNU MediaGoblin software is released under an AGPLv3 license. - -See the ``COPYING`` file in the source repository for details. - - -Is MedaGobilin an official GNU project? What does that mean? -============================================================= - -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/codebase.rst b/docs/source/codebase.rst index ba5f1e46..28d73802 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -45,7 +45,7 @@ Software Stack * Web application - * `Paste Deploy `_ and + * `Paste Deploy `_ and `Paste Script `_: we'll use this for configuring and launching the application @@ -83,22 +83,21 @@ After you've run buildout, you're faced with the following directory tree:: mediagoblin/ - |- mediagoblin/ #source code + |- mediagoblin/ # source code | |- tests/ | |- templates/ | |- auth/ | \- submit/ - |- docs/ #documentation + |- docs/ # documentation | - | #the below directories are generated by - | #buildout. + | # the below directories are generated by buildout. | - |- bin/ #scripts + |- bin/ # scripts |- develop-eggs/ |- eggs/ |- mediagoblin.egg-info/ |- parts/ - |- user_dev/ #sessions, etc + |- user_dev/ # sessions, etc As you can see, all the code for GNU MediaGoblin is in the @@ -108,7 +107,7 @@ Here are some interesting files and what they do: :routing.py: maps url paths to views :views.py: views handle http requests -:models.py: holds the mongodb schemas---these are the data structures +:models.py: holds the mongodb schemas---these are the data structures we're working with You'll notice that there are several sub-directories: tests, @@ -122,9 +121,3 @@ templates, auth, submit, ... and media item submission. If you look in these directories, you'll see they have their own ``routing.py``, ``view.py``, and ``models.py`` in addition to some other code. - - -Recipes -======= - -FIXME - write this diff --git a/docs/source/contributinghowto.rst b/docs/source/contributinghowto.rst deleted file mode 100644 index 8eaff5e4..00000000 --- a/docs/source/contributinghowto.rst +++ /dev/null @@ -1,215 +0,0 @@ -.. _contributing-howto-chapter: - -=================================== -HOWTO Contribute to GNU MediaGoblin -=================================== - -.. contents:: Sections - :local: - -.. _join-the-community-section: - -Join the community! -=================== - -We're **really** glad that you want to join the MediaGoblin community! - -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. - -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. - -Hang out with the MediaGoblin folk ----------------------------------- - -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 / Triage 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. - -If you want to contribute to MediaGoblin and don't know where to -start, look at the `bug database `_ -as a starting point. - -See the section on `bug triage <#triage-bugs>`_ for suggestions on how -to most effectively triage and approach the issue queue. - -Write/Fix Code --------------- - -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! - -Send Encouragement, Spread the Word ------------------------------------ - -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. - -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. - - -Help Others ------------ - -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. - - -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? -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 -the `Deployment HOWTO `_ - -.. _translating: - -Translate MediaGoblin ---------------------- - -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 --------------- - -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 -========= - -MediaGoblin uses a bug tracker called `Redmine `_. - -Our instance is located at ``_. - -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. Consider: - - * 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 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! - -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. - -.. _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: - -- ensure that one or two people in addition to the initial reporter - have been able to reproduce the issue. - -- 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 `_ -for more specific contact information. - diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst new file mode 100644 index 00000000..db92257a --- /dev/null +++ b/docs/source/deploying.rst @@ -0,0 +1,16 @@ +.. _deployment-chapter: + +======================= + Deploying MediaGoblin +======================= + +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) but if +you want to see where we are now, you can try to run the latest +development version by following the instructions on +`the wiki `_. diff --git a/docs/source/deploymenthowto.rst b/docs/source/deploymenthowto.rst deleted file mode 100644 index f3093a60..00000000 --- a/docs/source/deploymenthowto.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _deployment-howto: - -================== - Deployment HOWTO -================== - -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) but if -you want to see where we are now, you can try to run the latest -development version by following the instructions on -`the wiki `_. diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index c525d002..835a7e7a 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -5,25 +5,15 @@ Foreword About the MediaGoblin Manual ============================ -Welcome to the GNU MediaGoblin manual. This document targets several -classes of users, including: +This is the user manual for MediaGoblin. It covers how to set up and +configure MediaGoblin and the kind of information that someone running +MediaGoblin would need to know. -* 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. +We have other documentation at: -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://mediagoblin.org/join/ for general "join us" information * http://wiki.mediagoblin.org/ for our contributor-focused wiki -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 ================================ @@ -31,16 +21,15 @@ Improving the MediaGobiin Manual 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 +1. Write up a bug report in the bug tracker 2. Tell someone on IRC ``#mediagoblin`` on Freenode. -3. Send an email to Will ``willg at bluesock dot org``, or Sam at - ``sam@cyborginstitute.com`` +3. Write an email to the devel mailing list. + +Information about the bugtracker, IRC and the mailing list is all on +the `join page`_. -When you tell us about your issue, please let us know: +.. _join page: http://mediagoblin.org/join/ -* where you are looking (in git? url of the web-page?) -* what the issue is, and -* your thoughts on how to resolve it. +Patches are the most helpful, but even feedback on what you think +could be improved and how to improve it is also helpful. -We hope these materials are useful and we look forward to any and all -feedback. diff --git a/docs/source/help.rst b/docs/source/help.rst new file mode 100644 index 00000000..34d4f37e --- /dev/null +++ b/docs/source/help.rst @@ -0,0 +1,16 @@ +================================== + How to Get Help with MediaGoblin +================================== + +There are a couple of ways to get help with problems with MediaGoblin: + +1. ask for help on IRC + +2. ask for help on the devel mailing list + +Details for both IRC and the mailing list are on the `join page`_ of the +website. + +.. _join page: http://mediagoblin.org/join/ + + diff --git a/docs/source/index.rst b/docs/source/index.rst index 93b2a942..088b5359 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,12 +12,11 @@ Table of Contents: :maxdepth: 2 foreword - about_mediagoblin - deploymenthowto - theminghowto - contributinghowto + about + deploying + help + theming codebase - vision Indices and tables diff --git a/docs/source/theming.rst b/docs/source/theming.rst new file mode 100644 index 00000000..2f4fcb4c --- /dev/null +++ b/docs/source/theming.rst @@ -0,0 +1,8 @@ +.. _theming-chapter: + +===================== + Theming MediaGoblin +===================== + +We haven't implemented the necessary scaffolding to allow for theming +yet. Thus, this chapter is a stub. diff --git a/docs/source/theminghowto.rst b/docs/source/theminghowto.rst deleted file mode 100644 index 7b40685f..00000000 --- a/docs/source/theminghowto.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _theming-howto: - -=============== - Theming HOWTO -=============== - -We haven't implemented the necessary scaffolding to allow for theming -yet. Thus, this chapter is a stub. diff --git a/docs/source/vision.rst b/docs/source/vision.rst deleted file mode 100644 index fad248df..00000000 --- a/docs/source/vision.rst +++ /dev/null @@ -1,142 +0,0 @@ -========================================= - Design Document: GNU MediaGoblin vision -========================================= - -.. Note:: - - When we get a wiki, this will get moved there. It's here for now - mostly because we didn't have a better place for it. - -.. Note:: - - By the time you read this, it's very likely it'll be out of date. - - -This document attempts to describe the envisioned workflow of GNU -MediaGoblin, from a structural standpoint. For now, *nothing* in this -document is probably the eventual, final way that things will work. -Eventually as things come to exist, this document will hopefully be -refactored to describe how things *do* work. - -This documented on hopes, dreams, rainbows, and unicorns. And it will -come to fulfillment through a lot of hard work. Your hard work and my -hard work. - - -Look and feel -============= - -Default look and feel ---------------------- - -Mairin Duffy made mockups for something called Design Hub. That -project did a number of things differently than the way we intend to -go, but it's probably a good idea to steal a good number of ideas from -here. - -http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ - - -User profile mockup -------------------- - -Here's an ascii art mockup on how things might look for a user's page:: - - _____ - |_( )_| USER NAME - | | | - |_/_\_| - - Recent artwork: - ___________________ ___________________________ - | ___ ___ ___ | |_About_User_Name___________| - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | Some sort of self- | - | ___ ___ ___ | | description probably goes | - < | |pic| |pic| |pic| | > | here | - | |___| |___| |___| | | | - | ___ ___ ___ | | | - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | | - |___________________| |___________________________| - - ___________________________ - Recent favorites: |_Recent_activity___________| - ___________________ | New picture: DragonFace | - | ___ ___ ___ | | 4/2/2010 | - | |pic| |pic| |pic| | |---------------------------| - | |___| |___| |___| | | Sup yall this is some kind| - | ___ ___ ___ | | of mini blogpost. Maybe | - < | |pic| |pic| |pic| | > | the interface will allow | - | |___| |___| |___| | | for this? | - | ___ ___ ___ | |___________________________| - | |pic| |pic| |pic| | - | |___| |___| |___| | ___________________________ - |___________________| |_External_comments_here____| - | Dang! This stuff rocks | - | - Joe 4/2/2010 | - |---------------------------| - | Nice job on the dragon | - | - Morgan 4/2/2010 | - '---------------------------' - -So there's this type of interface that puts a lot of different types -of info on the same screen. I'm not sure that I like it. It's -possible we'll go with something much more minimalist. Maybe we'll go -with something "tabbed" the way statusnet / http://identi.ca is on -user pages. - -It's possible that we could support multiple profile styles here, -and you could load whatever profile style you want as set by user -preferences? - - -Uploading mockup ----------------- - -Here's an uploading mockup:: - - Upload an image - - [ Title ] - - Upload: [ ] [Browse] - ___________________________________________ - | | - | | - | o0O | - | o ' | - | o_.' | - | | - | Uploading... OK | <-, - | Resizing... OK | | - | | Area replaced w/ resized - | | image when done - |___________________________________________| - ________________ - License |_CC BY-SA_____|V| - ___________________________________________ - | Description goes here. | - | You can type it up in here and everything | - | and it'll show up under the image. | - | | - | Possibly we should allow some kind of | - | markup... maybe markdown? | - '___________________________________________' - - __________________________________________ - |> Advanced | - ------------------------------------------ - - -Customizability ---------------- - -General site theming customizability is pretty easy! Since we're -using `Jinja `_ we can just set up -user-overriding directories. - -We'll also figure out some sort of way to provide theming "packages", -eventually. - - -- cgit v1.2.3