Thanks to both of you (Michelle and Chris) for coming up with this plan. +1 from me.
Judy On May 31, 2011, at 5:18 PM, Christopher Brooks wrote: > Hey Michelle, > > Doesn't matter which one is the release and which the developer wiki, > I was just using it as an example. > > We can't move subtrees between spaces? How will we move the trunk docs > to the release wiki once they become bigger? > > Chris > > On Tue, 31 May 2011 16:25:10 -0700 > Michelle Ziegmann <[email protected]> wrote: > >> 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 >>>> >>> >>> >> > > _______________________________________________ > Matterhorn mailing list > [email protected] > http://lists.opencastproject.org/mailman/listinfo/matterhorn > > > To unsubscribe please email > [email protected] > _______________________________________________ Judy Stern Educational Technology Services, UC Berkeley [email protected] _______________________________________________ Matterhorn mailing list [email protected] http://lists.opencastproject.org/mailman/listinfo/matterhorn To unsubscribe please email [email protected] _______________________________________________
