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. 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. 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. 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. 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 > -- Christopher Brooks, BSc, MSc ARIES Laboratory, University of Saskatchewan Web: http://www.cs.usask.ca/~cab938 Phone: 1.306.966.1442 Mail: Advanced Research in Intelligent Educational Systems Laboratory Department of Computer Science University of Saskatchewan 176 Thorvaldson Building 110 Science Place Saskatoon, SK S7N 5C9 _______________________________________________ Matterhorn mailing list [email protected] http://lists.opencastproject.org/mailman/listinfo/matterhorn To unsubscribe please email [email protected] _______________________________________________
