[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: will kahn-greene
Subject: [GMG-Devel] docs (was 0.0.5 release, and today's meeting notes!)
Date: Sun, 04 Sep 2011 08:35:15 -0400
User-agent: Mozilla/5.0 (X11; Linux i686; rv:6.0.1) Gecko/20110830 Thunderbird/6.0.1

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.


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.

Also, we had a meeting today!  Here are the IRC logs:

Thanks everyone! :)
  - Chris

reply via email to

[Prev in Thread] Current Thread [Next in Thread]