A tale of two wikis

Wed May 11 16:34:55 UTC 2005

So the point would be to shift the work of organising all the
documentation from an automated content management system (portal) to
a published-by-humans wiki which draws from a draft wiki, right?  This
is to the _the_ consolidated source of documentation for ubuntu?

Ubuntuforums members, mailing list members and IRC users can all draw
from and contribute to such a document?

On 5/11/05, Henrik Nilsen Omma <henrik at canonical.com> wrote:
> Hello everyone,
> 
> I should finally introduce myself :) I'm going to lead the transition to
> the new wiki over the next few weeks and would like to start by getting
> everyone's view on it. I've set up a few websites in the recent past
> (Ubuntu.com, TheOpenCD.org, SoftwareFreedomDay, Bazaar) and have some
> opinions about what the documentation development website might look like.
> 
> The wiki is obviously a great tool in the way that it lets people
> collaborate on documents. I'm worried that setting up a portal system
> without full wiki functionality would be less useful. The wiki
> technology has proved itself in being very effective at producing
> documentation quickly, and I'm not confident that some other non-wiki
> portal system could be as dynamic. As it is now, there is a very low
> barrier to entry, which encourages people to come along and start a
> documentation page. The problem now is that there is no clear way of
> specifying when a page is 'done' as someone else can always come along
> and change it further, possibly for the worse. The question is, whether
> it is easier to add some workflow functionality to a wiki (or set of
> wikis) or easier to add wikiness to a portal system. I guess Plone is
> currently one of the more advanced portal systems available. We are
> running it with an integrated wiki ATM, but for various reasons are not
> very pleased.
> 
> So onto the ideas: I have an idea for using two separate instances of
> the Moin wiki to achieve the workflow we are after. One would be an open
> 'Drafting Wiki' (no pun intended) and one a 'Publishing Wiki', possibly
> with separate sections for Breezy, Perky, etc. The Drafting Wiki would
> function much as today's main wiki in that anyone can log on and edit
> pages or start new pages. The Publication Wiki by contrast would be more
> tightly bolted down, with a few editors making decisions on what
> material from the open wiki was ready for inclusion. The editors would
> generally be chosen from the doc team, perhaps through a nod from the
> Community Council.
> 
> The advantage of this proposed system is that it uses technology we have
> available today and uses the data in its current format. We have the
> opportunity to modify the user interface of each wiki in the form of
> altered skins. I could imagine leaving the Drafting Wiki much as a
> standard wiki (with an appropriately Ubuntu-ized look) while stripping
> down the Publication Wiki as seen by the public. The Publication Wiki
> could be integrated tightly with the main website, so that it would be
> obvious to new users that the documentation on there was the official
> one. If you didn't know any better, you would think that these were just
> static HTML pages. However, when logging in, the Publication Wiki would
> behave just like a normal wiki and the editors could move stuff around
> at will. It should be fairly easy to add a button to each wiki to allow
> you to jump to the equivalent page in the other wiki.
> 
> Wiki to wiki transfer: This may be the weak point in my plan, so please
> give feedback :) The idea is obviously to copy pages from the Drafting
> Wiki to the Publication Wiki when the pages are ready, or through some
> release cycle process. Initially we would simply do this by copying the
> source text from the Drafting Wiki to the Publication Wiki, but later we
> might code an automated transfer system with a queue. For now, we could
> ask contributors to ping a mailing list (doc-submission@ ?) when they
> feel a page is ready for inclusion (or updating) into the official
> stack. Editors would monitor this list and would make the transfer,
> making corrections as needed. The editors could also make comments to
> the entry on the list suggesting changes need for approval.
> 
> So, how do we keep things in sync (to the degree that we want them in
> sync)? How do we make sure it's maintainable? How do we get everyone to
> do 'the right thing'? At the moment, most people are doing 'the right
> ting' in the open wiki, though we do see some stray pages at times. With
> the proposed system it is more important that the handful of editors 'do
> the right thing' because we can afford to be a bit more loose with the
> open wiki. Fortunately it is easier to ask a group of 10-15 people to
> follow certain guidelines than 1000 people. One important step required
> to keep things sane, is that editors always make correction in the
> Drafting Wiki and then import, rather than making changes in the
> Published Wiki which might then not make it back to the Drafting Wiki.
> That way anyone could check what changes were made by looking at the
> page history. The Publication Wiki would in effect work as a repository
> of mature material that gets used for web pages, Yelp pages, PDFs, etc.
> It just happens to use wiki technology. This policy might be a bit
> cumbersome when you have to copy and paste manually, but we can see it
> as a first step toward a more automated system, where you can press a
> 'Submit' button in the Drafting Wiki and editors can select 'Accept',
> 'Reject' and/or 'Comment' directly in the Publication Wiki (some
> development required ...)
> 
> Publication: The next step in the workflow is to publish the mature
> material in various formats. The on-line help system seems easy, by
> simply allowing the Publication wiki to be world-viewable and integrated
> with the main Ubuntu website. The other important task is to convert the
> material to DocBook. Are you currently doing this manually? It should be
> possible to write a Moin to DocBook export filter, or at the very least
> make a super-simple Moin skin that would render the pages basically in
> pure HTML which can then be piped into DocBook with a simple script.
> 
> So, that's one idea for moving forward. Please comment.
> 
> Btw: thanks to Matthew East for the introduction in the recent 'Wiki
> Transition' post. I would indeed like to speak with some of you on the
> phone about this, and ideally organise a mini-workshop to get us
> started. I can organise something very informal here in Oxford at some
> point in the next few weeks (a Saturday perhaps?). How many of you are
> UK based and might be able to attend?
> 
> - Henrik
> 
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>