ffeathers — a technical writer’s blog

Calling all technical writers — are you a wiki hugger already, like me or just getting interested? Let’s get in there and make our voices heard. We’re in the front line, writing technical documentation and pushing it out to readers in far-flung corners of the world. Wiki technology has been around for a while, and many wiki developers are looking for new things to do with their product. New features and innovative mashups appear almost daily. Let’s speak up, tell them what we like, and help make wikis even better.

endithinks commented on my previous post, asking what the challenges are and when it would be inadvisable to use a wiki. And Don pointed out a couple of problems we’ve had to work around, when using a wiki for document management. He also identified the tree in my photo. Thank you, guys.

So, what does a wiki not do very well? Should it be doing those things at all? And what’s happening in that sort of arena?

A wiki is not a document management system. It’s not meant to be. If you need strict version control and records management for purposes of legal or other compliance, then you’d probably stick with a more traditional document management server, such as Documentum, Lotus Notes, SharePoint or what have you. Also, if you have a large existing base of documents in other forms, it would be cumbersome to upload them to the wiki and then ask your readers to view them as attachments to wiki pages. Instead, you might use a wiki as a knowledge management system running alongside your document server.

Keep an eye on the new stuff happening:

• Atlassian and Microsoft have announced a Confluence-to-SharePoint connector. This is exciting for those of us who know and love Microsoft SharePoint. The connector is very new, so it’s a free download while still in beta. If you’re interested, try it out. I think that this is a great time for technical writers and SharePoint power-users to have their say on what the Confluence-SharePoint integration should do. It’s a bit basic right now.
• An intriguing snippet of information in a comment from xaop on a blog post by Craig (2nd comment in the list) mentions integrating their Docbook publishing process from Subversion into their project website, so that customers can link tickets, wiki pages and comments into the docbook. I’d like to know more about that one.

Wikis don’t really do workflow. In most cases, a wiki is for instant gratification — view, edit, save, and bob’s your uncle. But again, things are on the move. Here are some new developments I’ve come across. Let me know if you’ve seen others.

• Comala Tech have written a workflow and approvals plugin for Confluence.
• Atlassian is working towards the launch of JIRA Studio, which will allow people to use Confluence (wiki) and JIRA (project management and issue tracking) on one integrated platform. There will be some interesting source control and review tools in there as well.

Wiki editors are not always easy to use. Many of them rely on wiki markup, and there’s not much standardisation of the markup codes used in different wikis. But things are on the move:

• DITA Storm offers a browser-based DITA XML editor which you can embed in your web application.
• A number of wikis offer WYSIWYG editors.
• I’ve used Confluence and Twiki. I much prefer wiki markup to a WYSIWIG editor. But many of my colleagues swear by the WYSIWYG editor.

I’m a self-professed wiki hugger, and I’m not alone in that. A wiki has a certain charm and gives ‘everyman’ a sense of power (that instant gratification again). And wikis do a lot of things very well indeed. Because wikis are the flavour of the month, even after being around for a few years, they’re growing and changing apace. Now’s the time to have a say in their development.

Let’s make ourselves heard. Download a wiki and try it out. Most wikis let you try one for free, and some offer an ongoing free personal licence.

Make a fuss about the things that wikis are missing (see all the comments on and the votes for this requested Confluence improvement) and pat the developers on the back for the bits they get right. Let them know we ♥.

If you’re interested in more ideas and experiences in using wikis for technical documentation, read some of my other blog posts on wiki docs and watch this space — more coming. Also, wander over to Anne Gentle’s blog and search for other wiki writers’ blogs.

There’s a lot more happening. Let me know what you’ve seen and done.

As most of you know by now, I am a technical writer at Atlassian. Each member of our technical writing team is responsible for documenting specific products. At the moment, these are mine:

Confluence is kind of: “Here I am – look at my buttons!” Crowd is the strong silent type: “I’m working away in the background, taking care of stuff for you. You won’t see me until you need me.” FishEye’s effortless charm hides a manic cleverness: “Here’s looking at you babe.“ Crucible offers with a nonchalant air: “Do you want to talk about it?“

When it comes to wikis, a good-looking GUI is really important. That’s GUI, not ‘guy’ – though a handsome man never goes amiss. You need to get intimate with your wiki. Every click should give a frisson of satisfaction. Every new page should look awesome on first save. It’s like a good first date. You want to want to come back for more. Delayed gratification is not what you’re after. Otherwise, you’d write the code yourself, in all those xxxML varieties, right?

So I’m really pleased that Confluence 2.6 is here. It’s been a long time coming, and it’s my first big release since I joined Atlassian. So I’m kind of fond of it. It comes with a new theme, more pictures dotted about, and a friendly style. Some people think it’s ugly, but I’m ready to go to bat on that one.

I had a lot of fun devising a new format for the release notes, with much input from other Atlassians. That’s the way things work in the company. You put up an idea, and everyone throws comments at it. After a bit, the final result emerges. Take a look at the new format of the release notes, and let us know what you think.

Some people have made Confluence their own by metagrobolising the look and feel.

Here are some pretty cool sites powered by Confluence: Toxipedia, CustomWare and thesarvo.

Are other wikis sexier than Confluence? And how about Microsoft’s SharePoint – is it pretty or friendly? Let me know what you think…