Thanks for the comments Chris. Some responses inline:
On 5/27/2011 4:55 PM, Christopher Brooks wrote:
Hi Michelle,
I've been thinking about this since you mentioned it awhile back and
would like to drop some ammendments:
1. That the first space just hold release docs. So 1.0, 1.1, 1.1.1
docs, etc. This set of docs is completely locked for editing, and only
the RM for a new release can move docs there.
Maybe I'm misunderstanding, but are you suggesting that we make our
current wiki space at
http://opencast.jira.com/wiki/display/MH/Opencast+Matterhorn+Project+Home the
place for release docs, and move everything else to a new "developer
wiki" space? If so, I strongly disagree with this idea. First, each
page has to be moved one by one, and by my estimates we've got around
900 pages in the current wiki. Second, the urls for all of those pages
will change, breaking hundreds of links across the web, people's
bookmarks, and in email archives.
I strongly suggest we start with a clean new space as the
"documentation" space and move the finalized release docs there. Then we
could easily rename the current wiki at
http://opencast.jira.com/wiki/display/MH/Opencast+Matterhorn+Project+Home to
"Matterhorn Developer Wiki".
When you say "just hold release docs", do you mean you don't want to
also include other "official documentation"? I think the license and any
official policies (like our pending security policy) belongs in the
official documentation, not in the developer wiki.
2. That the trunk doc stays on our "wiki". This is the working copy of
the docs that developers change while not in release mode.
Makes sense.
3. That we call the first space our "Documentation" and the second
space our "Developer Wiki". Makes it clear I think that if you want to
docs go to A, if you want some stuff that hackers are changing perhaps
frequently, go to B.
The titles make sense, but as I argued above, the first space can be the
"Developer wiki" and the second space "Documentation".
I don't love new spaces because I don't want to get lost, but this
would seem to be a nice even split so I am generally in favour of this.
We'll have to do some work to reduce the potential for getting lost, but
I really think people will be less likely to get lost this way.
What do you think about these ammendments?
Chris
This idea has been tossed around a few times with some of the product
owners, and it's a good time now to consider whether or not to go for
it. The basic idea is to create a separate wiki "space" for Opencast
Matterhorn Official Documentation. The way it would work is that all
"official" finalized documentation would be it's own wiki space. I
started this space to give you an idea:
http://opencast.jira.com/wiki/display/MHDOC/Matterhorn+Documentation.
Some advantages to this:
- Easier for new users to find official documentation vs. lots of
outdated and draft documents
- Lessens the criticality of wiki gardening in the current wiki
(proposed new title "Matterhorn development"), as it will be assumed
that anything in this space is possibly draft and/or outdated. This
allows the current wiki to function as an ongoing collaborative,
sharing and document development space.
- We can apply different permissions to the Official Documentation
space, to lessen incidences of unwanted changes to release
documentation or important things like our license or security policy
(in progress).
We can facilitate navigation between these 2 spaces by taking
advantage of the orange buttons in the left side navigation of both
spaces (they would point between the 2 wiki spaces), adding a tab at
the top "Official Matterhorn Documentation", and providing prominent
links in likely places for "Official Documentation".
There is a concern that search results won't be helped by this
approach, but this only applies when people use the search box in the
upper right corner of the page (because this searches across both
wikis). But if we can try to steer people to search within the wiki
(using the search in the left hand nav of
http://opencast.jira.com/wiki/display/MHDOC/Matterhorn+Documentation
for example, at least they will have a chance of finding the current
official documentation (more so than I think they have now). We can
also try to keep a current, intuitive listing of content on the front
page, which will hopefully eliminate the need to search.
This seems to be a common approach by other projects. Sakai, for
example, seems to create a new space for lots of small purposes
https://confluence.sakaiproject.org/display/CONF/Complete+List+of+Confluence+Spaces.
And they keep a separate space just for official documentation
https://confluence.sakaiproject.org/display/DOC/Documentation. Sakai
is just one example. Most open source projects that I looked at
require the use of several wiki spaces for each project, and almost
all of them keep Official Documentation as a separate standalone
space.
Is there anyone who has objections to this move? Are there downsides
that I've overlooked? Or suggestions for mitigating potential
problems?
Thanks!
Michelle
--
Michelle Ziegmann
===========================
Electronic Communications Specialist
University of California Berkeley
Educational Technology Services
_______________________________________________
Matterhorn mailing list
[email protected]
http://lists.opencastproject.org/mailman/listinfo/matterhorn
To unsubscribe please email
[email protected]
_______________________________________________