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

[Christopher Allan Webber]

Hey Jim, 

GREAT work on this inventory.  I think I agree with pretty much
everything you say.

This is a lot to get through, and I think starting to process through it
is a task in and of itself, but I'd like to continue some conversations
on IRC.

As I said, I think we're likely to be getting some additional help
shortly... I think this would be a good project for them.

Meanwhile, related things that we should maybe be getting through are:
 - the site switchover to Pelican, which is almost done
 - the old site redesign that Jef started and we never finished (augh,
   my bad!  I left it hanging on wording stuff...)

Again, good work, let's continue with this :)

Jim Campbell writes:

> 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
> _______________________________________________
> devel mailing list
> address@hidden
> http://lists.mediagoblin.org/listinfo/devel