--- title: "Guest Post: Wikis Are the Future of Technical Documentation" date: 2012-03-20 description: "$( document ).ready(function() { // Handler for .ready() called. $(" canonical_url: https://idratherbewriting.com/2012/03/20/guest-post-wikis-are-the-future-of-technical-documentation/ --- # 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. [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/orangebar.png)](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/2009/04/orangebar.png) 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](http://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.