A tale of two wikis

[Henrik Nilsen Omma]

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