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

[Christopher Allan Webber]

Definitely agreed on the more screenshots front.

One thing not discussed in this thread (but Nils and I have discussed it
briefly) is Jef's site redesign draft that puts screenshots more front
and center:

 - http://schendje.fedorapeople.org/goblin/homepage/wireframe3.png
 - http://schendje.fedorapeople.org/goblin/homepage/layout_explained.png

I'd like to see that also!  The tour page is sooooooo out of date.


Jason Li writes:

> Just a small addition – let's add more screenshots. I found it hard to
> figure out how the entire system worked from the screenshots available
> right now, and it was only when I installed my first test instance
> that I figured out the flow between the front page, uploading,
> detailed file view, creating a collection, etc.
>
> Keep up the great work!
>
> Jason Li
> hongkonggong.com
>
>
> On Aug 2, 2013, at 12:57 AM, Nils Georg Heinrich Reichert <address@hidden> 
> wrote:
>
>> 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
>> _______________________________________________
>> devel mailing list
>> address@hidden
>> http://lists.mediagoblin.org/listinfo/devel
>
> _______________________________________________
> devel mailing list
> address@hidden
> http://lists.mediagoblin.org/listinfo/devel