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

Reply via email to