You start to write about your application –

OK, you will need a front page and a couple of sub-pages – that doesn’t sound so bad, does it?  Many people have done just this on UserBase.  Some write directly onto new pages, some are happier to draft their work first, so use sub-pages of their User-space pages, and that works fine.  With our without the help of the UserBase Admins, the content can then be pasted into the correct tree structure and the draft removed – and everyone’s happy.  But what if you want to write a whole manual?

As the Amarok team have discovered, it’s a whole new ball-game.  You start with a Contents page, listing all the pages you think you’ll need, and you start to build.  Before you finish I’ll guarantee that you’ve thought of something that would have been better on a page of its own.  As it happens, that’s not a big problem – you can edit the contents page and create a new page that way.  But wait – what seemed good organisation to start with is less convincing now, and maybe it would be better to move things around, re-organise a little.  Hmm – not so bad!  There’s a little icon for Move – ah yes, it moves the page to the structure you want and even leaves a re-direct behind, in case someone uses the old link.

Sounds pretty good, doesn’t it?  Unfortunately this is where it starts to come unstuck.  Once you’ve finished, the Translators move in – and where should their links point?  If they translate from the original they probably will use the original link, which is now a re-direct.  That’s not good.  We have to clean up re-directs, in that case, and that’s when we find that moved pages have been moved yet again, causing double-redirects – an even bigger job for cleaning up.  You see, we can’t just delete them – there could be a number of pages that link to the old page, so we have to track all links, and in the case of the double-redirect we have to do that for both levels of old pages.  It can be quite difficult to follow, but it’s a necessary part.  Happily we have almost finished the double-redirects – heaven preserve us from triple-redirects!

“So you said I could make it easy for myself?”

We think so.  It’s experimental, yes, but it should help anyone starting new documentation.  Most of what you see on UserBase is in the “Main” namespace, but today we have opened up a new namespace called “Draft”.  You can start your documentation there without worrying about the issues I’ve just talked about.  Move things around as much as you like – just remember that in the end any page links will need sorting!

The idea is that when the pages are ready we can simply move the whole structure into the Main namespace if any redirects have been dealt with, but if it has proved more complex and things have been moved around a lot we can use Copy/Paste to create the Main pages from the Draft ones, fixing links as we go and losing all the redirects on the way.

One last thing – you have to be the main writer for your documentation, and you are used to an entirely different kind of mark-up, finding that attempting Mediawiki mark-up gets you utterly confused.  We can handle that too – and again the Draft namespace is the best place to do it.  Put your plain text there.  Add any markup that will be obvious to us, for instance <bullets>,  and we will help you get it looking the way you want.

Using Draft  should remove a good deal of anxiety and hassle, but we need you to try it out.  Take a look at Draft and let us know what you need to make it even better for you to draft your documentaion.  See you there!