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