Wikis for technical documents – interview with Alan Porter

Here is the edited version of Cherryleaf’s transatlantic Web interview with Alan Porter on wikis and their use for technical documentation:


mick davidson

I agree with a lot of what Alan says, having a wiki definitely makes it easier to get information that would have been lost in silos in front of clients. We’re definitely experiencing this. Another benefit is the ability to respond to new needs, and get them in front of clients with minimal hassle and very quickly, often with minutes. Our wiki software (from Mindtouch in the USA) comes with a great wysiwyg editor that anyone can use, but you can also work in HTML as well. It’s a very flexible way of working. As for using it as well as or instead of Help, we’re looking at ways of linking the software directly to the relevant section in the wiki. A slight negative we’ve experienced so far is that the levels of take up amongst staff has been lower than we’d hoped – but it is growing. And some staff are concerned about the quality of their writing, so they are nervous about making changes that may not adhere to our high standards of literacy. That really isn’t an issue as the documentation dept gets notified within minutes of every change/edit in the wiki. This means we can review the changes and correct them if necessary. If a change anyone makes is significant enough, we put a linked note in the page updates area. Clients not only find out very quickly when something changes, they have some information about what’s changed and can jump straight to it. Talking about linking, we link from user info, to How Tos, to FAQs, to white papers etc very easily. So instead of seeing documentation as a series of groups, it’s all just one part of a big ball of information that you can navigate quickly and easily, following your own path and not getting stuck in dead ends. As far as I can see, having a wiki for your documentation has got to be the way forward and is, in my experience, light years in front of any other way of doing it.

Sarah Maddox

Thanks for a great interview, Alan and Ellis! It’s great to hear Alan talking about a range of different wikis. My experience has been principally on just one wiki (Confluence), so it’s interesting to hear how other wikis tackle the same requirements.

One thing I’d disagree with you about, Alan, is the preference for search, tempered by labels and tags, rather than a table of contents that shows a hiearchical tree of pages. I don’t think it’s a generational thing. Instead, it depends on the type of reading the user is doing (looking for a particular fix, or getting an idea of what a product can do) and on the type of documentation (technical user/admin/installation guide as opposed to intranet or project documentation).

A table of contents, showing all pages in the documentation base, is a great way to give the reader an idea of the scope of the documentation. Without that, they have no idea how big the documentation base is. It tells them that there’s a user guide, admin guide, installation guide, FAQ section, etc. They can open the user guide node in the tree to get a quick overview of the type of functionality provided by the product. And so on.

A table of contents also helps people to find information when they have no idea what term to search for.

Originally our technical documentation wiki did not contain a table of contents, because the wiki software did not support that. In response to frequent and numerous requests over a long period of time, we eventually added the feature to the wiki software and therefore to our documentation wiki too. When we added the table of contents, there was a gasp of understanding and a sigh of relief throughout the company, as well as amongst our customers. Our staff and many of our customers are of the younger rather than older generation. 😉

One huge benefit we found was that, as well as helping people to find information, the table of contents helped prevent the organic spread of new pages that tends to plague wikis. Our support staff, developers and others can update the wiki at will. The tendency was to do a quick search, then just add a new page with a smidgeon of information if it wasn’t easy to find any existing content on the same subject. With the table of contents, the organised structure of the documentation is more apparent and people tend to be more conservative about adding new pages.

Mick,great closing line: “As far as I can see, having a wiki for your documentation has got to be the way forward and is, in my experience, light years in front of any other way of doing it.” I started working on a wiki 2 and a half years ago, after 10 years doing tech docs on other tools. Your feeling is just what I feel too.


mick davidson

Sarah et al, Navigation of our wiki can be from the navigation panel on the left, where every page is listed alphabetically unless we force it not to be. Each page and it’s sub pages has their own TOC (collapsed and expanded at will). Each main topic may or may not have a TOC of it’s sub pages (if they do, we add a simple piece of code that automatically populates the TOC) to make navigation easier by showing, at a glance, its related pages. If a main topic only has a couple of subpages, we generally don’t bother. But some have a dozen or more sub and sub-sub pages, so these do (the TOCs tend to show one level, but can show two or more).
In practise we find that experienced users do a search for a subject as it’s almost always quicker to get where you want to go. This means we don’t have to drill down through the nav panel. But if you’re looking for something and don’t know where it is, or you want to get an overview, then the nav panel is perfect. You can also look at the site map. And the search is pretty amazing in terms of how many options you can use. For example, you could just search on a simple one-word term, or multiple words, put them inside double quotes if you want to get specific, do boolean searches etc. The list of options is very long.
As for people adding new info in random places, so far this hasn’t been an issue. We can control things pretty well as our wiki isn’t massive and is used (currently) by only about 300 people, of which only 70 have editing rights. Because we have structured our info (the software is massive but can be broken down into modules, each dept has it’s own area etc), people generally start in the right place. We have also set it up so that those with edit rights can create docs in their own areas before making them public. Which means the info has to be passed by the docs dept before being seen by clients.
I’m hoping the ISTC awards this year might cover wikis, I’m not sure the current categories do. Apart from being the future, they also make my job more interesting and rewarding, and therefore I am more motivated. 🙂

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.