[GMG-Devel] docs (was 0.0.5 release, and today's meeting notes!)

[will kahn-greene]

Sorry about that.  I was building furniture yesterday and plum forgot 
about the meeting.

I saw a docs-related questions in the logs.  We've picked up some new 
people, so I figured I'd rehash the complete docs situation.

The history of the documentation situation is this:

1. When the project, I elected myself documentation czar.

2. We (Greg, Asheesh, Deb, Karen, Elrond?, Caleb?, probably some others) 
talked about things for a while and decided that we need to write 
documentation for three different audiences: site administrators, users, 
and contributors.

3. In the meantime, we threw all our documentation into the mediagoblin 
repository in the docs/ directory to more easily bootstrap the project. 
 We're one of the only projects I know of that had the level of 
documentation we had from the very beginning.

4. Since then, it became an issue that we needed to make it easier for 
more people to contribute to the contributor documentation.  We were 
having issues with virtualenv, buildout, running mongodb, setting things 
up on OSX and other systems, ...  We'd work through these things on IRC, 
but then needed to codify them.  We decided to create a wiki for these 
things.

5. In June or July or so, we decided to move the contributor-related 
content from the docs/ directory in the mediagoblin repository to the 
wiki.  Jim, myself, and others worked out a rough plan on what should 
get moved to where and how it should be re-organized.

Also at that time, I started trying to figure out how to migrate our bug 
tracker.  Because of that, I haven't spent the time on this that it 
warranted.  I see some edits in the wiki, but otherwise, it seems like 
because I dropped the ball, nothing really got done.


That's the history of documentation.


Let's step back a bit and talk about our project requirements for 
documentation.  They are these:

1. We have three audiences we're catering documentation to:

* site administrators
* users of MediaGoblin instances
* people contributing to the project

2. When we do a release, we have to include site administration 
documentation in at least Texinfo form in the source tarball.  That 
documentation needs to be versioned alongside the rest of the 
MediaGoblin source code.

What we actually do is build the docs/ in HTML and Texinfo forms and 
include the compiled versions in the source tarball.  I implemented that 
in 0.0.4 and honed it a bit for 0.0.5.

3. We need to be able to hone our contributor documentation quickly so 
that as we learn about issues, we can fix them and continue to reduce 
the barriers to entry for contributors to the project.  To make it 
explicit: contributors are *not* just developers.

4. It'd be nice for users to be able to access user help documentation 
from within MediaGoblin.  That'd make it easier to do context-sensitive 
help.  e.g. I'm on a page for uploading images, how do I use this form? 
 Also, we'd probably want to do FAQ-oriented help, too.  That should 
also be tied to the source code.


Given that, the current docs situation is this:

1. Manual-related docs for site administrators and users are all going 
to be in the mediagoblin repository in the docs/ directory.  We're using 
Sphinx from hg tip to build those as HTML and also Texinfo.  Those get 
build when we do a release tarball.

2. We're thinking about building an in-application help system for user 
documentation, but that hasn't been worked on, yet.

3. We have a wiki where we're putting all contributor-related 
documentation.  Putting it in the wiki allows us to be agile about it 
and hone it as we need to.

4. We're splitting the documentation into three domains:

* Tychoish is going to take over the manual documentation in the docs/ 
directory of the mediagoblin repository.

* I'm going to continue managing the contributor documentation in the wiki.

* No one is slated to own the user documentation in the application.

5. Owners lead that documentation project.  If you want to make changes, 
it's best to talk about it with the lead.  Anything that needs to get 
done should have an issue created in the issue tracker.  This makes it 
easier for us to coordinate documentation efforts.

6. The Sphinx docs need some more Sphinx-fu (index, better templates, ...).

7. The wiki docs need some more wiki-fu (some basic templates, 
re-organized into categories, a front-page that has a better narrative 
making it easier to figure out what you're looking for, ...).


One issue I currently have is that documentation is an ongoing project 
just like writing source code.  The continual harping on "we need to 
work on documentation" bereft of specifics of what needs to be fixed 
isn't very useful.  I'd like to reduce that chatter and talk about 
specifics going forward.  Examples of specifics could include "new 
contributors find it difficult to figure out where the mediagoblin 
environment setup docs are", "site admins need to know how to deploy on 
nginx", "we need to reorganize the contributor docs so it's easier for 
someone new to find something they can work on", ...

Also, specifics should be tied to an issue wherever possible otherwise 
they get lost in the shuffle.

Also, if you don't know something, *please ask*.

Also also, we have specific people wearing lead hats on this project and 
we should document that somewhere so that new people know who to ask 
with questions about various domains.  Where should we document that? 
The wiki?

I think that covers everything I know about documentation.  I'll write 
this up in the wiki today in a better form.

/will


On 09/03/2011 11:08 PM, Christopher Allan Webber wrote:
> Hey all!  You've probably already seen but we released a new version of
> MediaGoblin, v0.0.5!  It's definitely our most awesomest release ever.
>
>    http://mediagoblin.org/news/version-0.0.5--visions-of-the-future.html
>
> Also, we had a meeting today!  Here are the IRC logs:
>
>    http://mediagoblin.org/irclogs/irc_meeting_2011-09-03.txt
>
> Thanks everyone! :)
>   - Chris