Guest Post: Wikis Are the Future of Technical Documentation
The following is a guest post by Mick Davidson, a technical writer with 20 years of professional writing experience.
Before I get started I'd like to thank Tom for giving me this opportunity to bang on about why I think wikis are the future for technical documentation.
Like many writers, up to a few years ago I was plodding around using backwoods technology, stuck with systems that had once been great but now begged to be retired. From a personal angle, I felt I was stuck with dull tools, tools that were not joined up, couldn't talk to each other, and excited me not one jot.
Then in through the window came the wiki — and everything changed. Now, three years on and two wikis later, I am 100% convinced they are going to be one of biggest and best documentation tools we have. In short: revolutionary.
There are perhaps four reasons for this:
- They are simple to use.
- They are very flexible.
- They expand as your content grows.
- They make life as a technical author an absolute joy.
The latter is particularly important for me as I do not go to work to trudge through thousands of words with something as dull as a word processing package. I don't want to use a system that hedges me in: I want more. I want a technology that gives me what I need and a lot more besides. And I want excitement!
There is at least one wiki system that offers all this. This system is called Confluence, by Atlassian, an Australian company that has, in less than ten years, come from nowhere to being a major player with 18,000 clients worldwide including Adobe, Twitter and Facebook. This is enterprise with a capital E. But don't just take my word for it, see for yourself at www.atlassian.com.
There are many other wikis out there, and I'm sure many of them are very good, though I'm not sure they are all enterprise level. Small can be beautiful, but corporations want technology that punches at the same weight as they do — or higher, and because they want to feel safe. MS Office is everywhere because it delivers the goods for many businesses. However, MS Office does not and cannot do what I felt we needed. And nor did any other system I investigated, all of which were far too rigid and expensive.
What we needed was a flexible, extensible system with built-in macros that enabled us to extend what we once called documentation into what is now known as content. Content can be words and graphics, as well as slideshows, audio and video etc.
The system also had to allow us to build and expand the structure as we needed to, easily and without fuss. As a lone author, I don't want to spend my time building pages and structure — I want to spend it on content that is, for users, as interesting and rewarding to read and experience as it is for me to create.
So, apart from all that, what does working with a wiki offer technical writers? How does it let us do our job better? Why is it more fun?
For a start, the wiki offers simplicity in every direction. In Confluence, and this may not be true of all wikis, it's ridiculously easy to create a set of pages that are linked to each other and to pages elsewhere. Structures form of their own volition as your content expands. Styles and formatting, which are already set up but can be changed by editing the CSS, are enforced throughout all pages, even when you import a Word document. Sure, you can't stop people adding their own styles, but you can't in Word either. And, as technical authors, we obviously don't need to be told to stick to our in-house styles, so using what's there isn't a problem.
Two of the biggest advantages are searching and linking. For me, these two things are possibly the most crucial elements. If there was one thing clients used complained about, it was the limited search capabilities offered by more traditional documentation. Before the wiki we had something like 70 user guides, how-to guides, white papers, and various other documents. If you wanted to find something you had to go through each document, one by one — which is a tedious and often frustrating process, especially if you're looking for topics that might be in more than one guide. A wiki can be viewed as a database of information that lies behind a very attractive front end — all of which is searchable at the same time.
With a wiki, everything is connected. Run a top level search and you search all your user information — in a second! And if you get too many results, you can simply modify or refine your search to focus it onto content sub-sets, by using labels (or tags as they are also known). In Confluence you can also search by date, the page's author, and content type. For example, you can search the graphics as well as page names and words. In the end, both you and your clients benefit from this functionality.
And yes, I know you can achieve quite complex searches in other systems, but in my experience, you cannot create them as easily and quickly as you can in a wiki.
Wikis also offer advantages with linking. Links not only provide an alternate way of navigating, they take you to related content, wherever it is, so you can surf pages in the same way you'd surf content in any other website. The fact that you can link to specific topics directly from your software (surrogate help?) is brilliant for lone authors and those with limited budgets and time.
And these are just a couple of the benefits. We haven't begun to explore collaboration. We're now getting developers to write user content of their own free will, and clients help us improve documentation by adding comments.
Did I tell you that I've just started setting up a user forum in our wiki? Yes, me, the technical author, not a programmer or a web developer. With the wiki this opportunity is in my hands.
Then there's the ridiculously cheap price. Well, in Atlassian's case anyway. I doubt that you'll find anything that offers so excellent value for money as a Confluence wiki. Ok, maybe you will if you're looking at their other products such as JIRA.
For the last 12 months I've been writing all our user information in our Confluence wiki. Before that I used another enterprise-level wiki for two years. Enough time, I think, to get a very good picture of what wikis can do and understand what their potential is. And I strongly believe they are the future. So much so, that nowadays I'm only really interested in working for businesses that use them. Anything less would be, well, less.
But don't take my word for it. Find a wiki that seems suit your needs, download a trial version and see how you get on. I doubt very much that you'll regret it.
Mick Davidson has been a professional writer for 20 years as a journalist and technical author. He works mainly in the software industry and attended Atlassian's recent Unite conference in London, where he took nine pages of notes. He can be contacted via at [email protected]. You can follow his blog at http://davidsonmedia.weebly.