[GMG-Devel] Proposed updates to website and docs structure (long)

[Jim Campbell]

Hi All,

I've been working on a content inventory of the MediaGoblin website, wiki and docs, and even though it isn't completed, I wanted to share the current progress with the group.

First, I want to say that the purpose of this is just to help better organize the information that we have. MediaGoblin has been under active development for a good while now, and certain parts of the docs have gelled to a point where we can see that they might make more sense (and be easier to find) if they were grouped together differently. I'm not really looking to remove the awesome info that we have, just change how it's structured.

Here is a rundown of what I have in mind, though. Feedback (via encouragement, criticism or blank stares) is welcome.

0) Change the top-level menu on MediaGoblin.org to look like this:  

"News | Tour | About | Community | Documentation | Contributor Wiki " 

. . . or something similar. Read the comments below, but I'm open to tweaks.

1) Adding an "About" page. 
- Why:  MediaGoblin is a unique project. A Flickr user needs to have a clear idea of the rationale behind the project to make it compelling for her to switch to MediaGoblin. We have information about this, but it's spread out. Having a central location for all of the "what is MG?" + project origin / history / philosophy stuff can help answer potential user contributor questions about what the project is, why it exists, and why they should care. 

- This can hold a brief statement about what MediaGoblin does / how you can use it, the origin of the project, info and links to Autonomo.us / GNU resources, and (a link to information about) joining the community.
- Inspirational pages: https://fedoraproject.org/wiki/Overview, 
https://fedoraproject.org/wiki/Vision_statement, 
https://fedoraproject.org/wiki/Foundations

2) Refine the "Community" page to be a little more comprehensive. Kind of like a "tour" of the community, but without as many pictures. 

- Why: Much of the information about joining the community is static (e.g. we have a ML and IRC, we have monthly meetings, you can get involved by joining X, Y and Z teams, etc.), and I'd like to increase the prominence of our fast-moving developer documentation in our contributor wiki. The general click path would go Community topic -> Contributor Wiki or just directly to the Contributor Wiki.

- Provide big, simple, primary links to some of the "join" page content (e.g., IRC, Mailing List, and Meetings (meeting date info would still be kept on the wiki) so that people can just get that info if they want. 

- Provide sub-sections on the page for the various ways people can get involved (filing bugs, sending encouragement, write docs, create a theme, create a plugin, use it, etc.). This would largely be simplifying and organizing information from the wiki.

- Relevant instructions on how to actually do each of these things / participate with these groups would be kept on the wiki, but the developer documentation would be moved up to be more prominent on the wiki. 
- Inspirational pages: http://fedoraproject.org/en/join-fedora, 
https://wiki.openstack.org/wiki/People (this is nice, but could get 
outdated if we don't maintain it), 
https://fedoraproject.org/wiki/Fedora_Project_Wiki (see the bottom 
section that lists the sub-projects)

3) All of the Contributor / Developer docs would move to the wiki. 
- Why: For contributors, using one spot (the wiki) as a home-base for developer docs will keep them from having to jump from place to place. I think the wiki is good for developer docs because development is moving so fast - I don't want merge requests to be a bottleneck. As an example, if someone is working on OAUTH stuff, I would want them to be able to sketch out their approach on the wiki so that others can immediately get an idea of the intended implementation.

- This means that the Core Plugin documentation, Plugin Writer's Guide and Developer Zone would move from the Sphinx docs to the Wiki.
- I don't have the exact org structure of this fully fleshed-out yet.
- Inspirational pages: 
http://docs.openstack.org/developer/nova/devref/index.html (even thought
 it's in python-sphinx, some of the types of topics are relevant )

4) Documentation moves to it's own heading off of the main MG.org page. 
- Why: Given that people will be installing and maintaing MG on their own, I think it's important to make docs a top-level menu item. This partly comes from my own experience with the Gitlab.org homepage. I go there to find their documentation so I can deploy or update their software, and they make it difficult to find how to do it (even though their docs are good overall.) On the other hand, OwnCloud.org does a great job with their deployment / administration documentation. I want to go in the direction of what OwnCloud has done.

- Docs will stay in python-sphinx, maintained in git.
- The documentation page is geared toward administrators and (later) users. The admin guide would include instructions for installation via manual installation, package managers (once MG is packaged by distros), configuration, and upgrade instructions. 

- Much of the manual installation info will come from the current deployment docs. I'll be working out the mapping of existing content to here.
- Note that configuration and upgrading are separate sections. I've been using Gitlab for a couple of months, and I really like the clarity of their upgrade instructions. Just having a separate upgrade page we can point to would be very helpful when release time rolls around.

- Inspirational pages:  http://doc.owncloud.org/ and 
http://doc.owncloud.org/server/5.0/admin_manual, 
https://github.com/gitlabhq/gitlabhq/blob/master/doc/update/5.3-to-5.4.md

I haven't worked out all of the migration details yet. My main thing is that I want for these changes to be useful for folks. I don't want to throw out a lot of the awesome stuff we already have. It's more about shifting things around, and making information more easily accessible.

5) Tone should be kept inviting and informal where appropriate. 
- We don't want to be making jokes in the deployment guide, but we should write with a warm style. I linked to a lot of Fedora examples just because of how they incorporate artwork in their wiki and docs to give it more warmth. I'm not sure how much artwork we'll be able to include, but we should keep the docs friendly.

Here are some questions:
- What do you all think about centralizing the contributor documentation in the wiki?
- What do you think about making the community page more comprehensive?  Should we just have a separate section in the wiki for the community details, and have only the deployment / config / update / user docs be in python-sphinx?

- What other documentation resources out on the web do you like that you'd like us to keep in mind as we work on this (i.e., what other "inspirational pages" exist for you"?)

If you've made it this far into this email, you deserve some snacks. Thanks for reading. Let me know what you think, 

Jim