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

[Nils Georg Heinrich Reichert]

Hi Jim and all,


I've been going through this proposals while trying to make myself familiar 
with the current and future setup of the website.
In this mail, I will try to synthesize some thoughts I've had. 

Many thanks, Jim, for getting this list together.

Am Thu, 25 Jul 2013 23:36:35 -0500
schrieb Jim Campbell <address@hidden>:

> 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.

The first small tweak I would like to add here is a small but noticeable visual 
distinction between entries that lead to the different contents of the main 
page (News/Tour/About/Community) and the entries leading to a differtent 
system/interface (Documentation/Wiki)

I've been thinking about the order of entries as well and came to the 
conclusion that the one already proposed is very well choosen.

It seems to me the six items could mentally be grouped into three couples:
The first two create curiosity or attraction.
The second couple tries to invite and convince.
The last two supply additional ressources for preparation.

Going along with this, there are some questions that maybe could be
used (in accordance with 5) inside the different pages in order to knit
them together and possilby incite a relation to the visitor as
well.

1. Are these people/goblins doing something?
2. What is it?
3. How and why? Could I?
4. Where and who? Would I?
5. Am I prepared?
6. What will we be doing?



> 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

Is there any place such information should be collected before it gets on this 
page? How will it be drafted?

Maybe we could also add certain social contracts of distributions like
Debian to the list of inspirational ressources:
https://www.debian.org/social_contract


> 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)  

Yes, comprehensiveness seems like a very good idea here! We will have to be 
careful to keep the structure clean on this page.
I really like the idea of having a second "tour", though – maybe with the 
ability to subscribe/join instead of viewing an image.


> 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 )

Makes a lot of sense to me! Should we introduce a category or any other 
structure in the wiki in order to collect documentation or guides that have 
matured to a certain point of complexity? Does this already exist? Does it work 
through prominency on the wiki main page?

> 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.

This almost seems to be a project of its own.
Could we perhaps get a better picture of how to progress here once 3) is done 
and maybe produced insights on how documentation is stuctured on the wiki? Or 
would looking to much into this lead us to not less but more questions?
Possibly that's just me who needs still some time to be completely familiar 
with everything.

> 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.

Awesome!

> Here are some questions:
> - What do you all think about centralizing the contributor
> documentation in the wiki?

I'm all for it. This might also help in setting apart wiki and general docs. To 
be honest, when I first intented to set up a GMG instance, I wasn't sure if I 
should follow the wiki or the manual, in case one maybe would be more up to 
date than the other.


> - 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?

It seems a good idea to keep Sphinx really clean. But a small spot for contact 
options and community could be helpful and inviting as well.
If the wiki is the main place to learn more about community details, I think we 
need to be especially aware that in a contributor's wiki everyone willing to be 
part of the community can feel as a contributor.

> - 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

Thanks again for starting this discussion,
Nils