Wiki docs – technical documentation on a wiki

Can you use a wiki for technical documentation? Yes!

Is it a mindshift? Yes!

Is it fun? Yes!

Am I a wiki hugger? Yes!

I’m a technical writer with nine years’ experience. I’ve used many tools of the trade, including Microsoft Word, Adobe Acrobat, RoboHelp, XDK, Help and Manual, HTML Help, QuarkXPress, Documentum, Lotus Notes / Domino and Microsoft SharePoint. And now I’m using Atlassian Confluence, a wiki. Yes, I’m biased, but with good reason ;)

Writing technical documentation on a wiki is what I do every day. Here’s an example. So I’ve decided to write a few blog posts about it. This post is one, and there are more to come. So watch this space.

Like other media, wikis have a lot of advantages and also some quirks. Treat your wiki right, and it will come through for you. Often it’s a matter of recognising a wiki’s strengths and using them in a creative way to perform or even replace a more traditional function. For example, you could try using labels/tags to generate:

  • The index – see my previous blog post.
  • Lists of ‘related topics’, which we often put at the top or bottom of an online help topic.
  • Frequently asked questions (FAQ).

So, let’s get down to the nitty gritty.

First, you might have the luxury of choosing your wiki.

Here are some things to consider:

  • Does your wiki allow you to restrict access to the pages, and what permission levels does it allow? For example, you might want to prevent anonymous users from seeing anything at all. Or you might allow everyone to view your pages, but only logged-in users can comment on them and only users belonging to a certain group can add, edit or delete content.
  • What overall structural framework does the wiki provide, to allow you to organise your manuals, chapters and pages?
  • How easy is it to structure the information within a page using styles, headings, frames, etc?
  • How easy is it to upload and insert images?
  • Does the wiki let you export/download the content into another medium, such as PDF or HTML?
  • Do you know anyone who is using a wiki for technical documentation, and can you get some tips from them? Alternatively, take a look at some of the documentation already published on a wiki. I’ll put some examples at the end of this post.
  • Does the wiki keep a history of changes to a page, and allow you to revert to a previous version?
  • What tools are there to help your readers find information, such as indexing, table of contents and search?
  • Does the wiki allow customisation – at the highest level of adapting styles and presentation, and at the deeper levels of allowing you to add plugins, change the default page layouts and even change the source code?
  • How vibrant are the developer and user communities – is there ongoing development and support of the wiki?

Here’s a really useful tool: WikiMatrix lets you compare wikis. You can even your own requirements to see which wiki is best for you.

Now that you have a wiki, start planning your documentation:

  • Consider the overall structure of your documentation suite, much as you would plan a user guide or a set of documents written in Word or something else. Plan how that structure will fit into the wiki’s framework. For example, you might want to write a user guide and an administration guide, each consisting of sections, chapters and pages. Will you put each guide into a separate instance of the wiki? If you are using Atlassian’s Confluence, you might consider putting each guide into a separate ‘space’ (a sort of wiki within a wiki). Or you might use a space to collect all the documents for a particular product – that’s the route we’ve chosen. For example, our Crowd space contains the user guide, administration guide, installation guide, etc.
  • Think about the structure of each page. If your wiki allows you to create templates, that’s useful. But a light touch is best here. Given that you’re probably going to have multiple authors with different styles and skills, I’d go for overall consistency of look and feel rather than detailed content-level standardarisation.
  • Think about the style and character you want for your documents e.g. formal or chatty, stylish or basic. Tailor your use of styles, macros, colours, etc to suit this character. In the list of wiki documentation sites at the end of this post, you’ll see a few different styles.
  • Plan your permissions - who should be able to do what. We allow all Atlassian staff full edit rights. Non-Atlassians and anonymous users can add comments and of course can view the pages.
  • Remember that it’s a wiki, so its power lies in its flexibility and dynamism. Don’t lay down too many rules, and do allow as many people as possible to edit the pages.
  • Have you hugged a wiki today? Get intimate with your wiki’s capabilities and tools. If your wiki allows you to install extra plugins and macros, get to know them too. This will help you quickly find a solution to any questions that arise.
  • Think about your labels or tags carefully – plan them as if you were planning the keywords for an index in a more traditional type of documentation.
  • You, as the technical writer or person who owns the documents, should subscribe to an RSS feed or a watch-list of all changes and comments. That allows you to monitor what’s happening and tweak the content if necessary.

Jump in, create a page and start writing.
Some examples of technical documentation published on a wiki:
Atlassian’s documentation and discussion site
Atlassian Confluence Hosted Administration Guide
Atlassian Crowd documentation
Adaptavist User Guides
GigaSpaces
Ubuntu User Documentation

I’ve run out of time – if anyone has any more examples, I’d love to hear about them.

Watch this space:

Do you feel that this post has raised more questions than it’s answered? I hope it’s given some good starting points. And stay tuned for more – I’ll expand on some of the points in my next blog posts.

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 4 November 2007, in atlassian, Confluence, indexing, technical writing, wiki and tagged , , , , , , . Bookmark the permalink. 16 Comments.

  1. These lists offer great criteria to use when choosing a wiki. It’s not quite like choosing an online Help Authoring Tool or a print tool or a blogging tool or a web design tool. Also, your pointers to examples are great.

    Here’s my list of techpubs wikis that I’ll be using in my presentation to the Austin STC next week, also in my STC Intercom article, “The Quick Web for Technical Publications” at http://stc.org/intercom/PDFs/2007/20070910_16-19.pdf.
    Everyone I talk to online loves the GigaSpaces wiki example.

    * Adobe Labs: labs.adobe.com/wiki/index.php/Main_Page
    * Apache wiki: wiki.apache.org
    * eBay: http://www.ebaywiki.com
    * Microsoft Developer Network (MSDN): msdn2.microsoft.com/en-us/library/default.aspx
    * Motorola Q: http://www.motoqwiki.com
    * SplunkBase: http://www.splunk.com/base
    * Sun’s OpenDS: http://www.opends.org/wiki
    * iMIS Community: http://www.imiscommunity.com

  2. The person who created the Gigapsaces documentation is a big proponent of wikis for tech documentation and today does consulting for tech writers who are exploring other options. His website is http://wikionlinehelp.com.

  3. Hello,

    May I know how do you customise the sidebar in the Crowd documentation? What are the necessary codes to customise it?

    Thanks and Regards,
    Zack

  4. Hallo Zack,

    We use the {pagetree} macro, which is supplied with the PageTree plugin. You’ll need to install the plugin onto your Confluence installation first, as it’s not bundled with Confluence.

    Basically, we put the macro into a page, which we name ‘TreeNavigation’ or something similar. Then we edit the page layout for the space, adding a bit of code to insert the ‘TreeNavigation’ page into the layout so that it appears on every page.

    There are some more links and instructions here:

    http://confluence.atlassian.com/pages/viewpage.action?pageId=96076078

    Let me know how it goes :)
    Sarah

  5. Wow, thanks for the tip Sarah! It’s wonderful! Now i can really organise my documentation more effectively.

    Zack

  6. Hi Sarah,

    Just wondering, is it possible to exclude the sidebar for the space page only? I wish to leave the navigation out of my main page.

  7. Hallo Michael

    Hmmm, I wouldn’t know how to do that. It’s probably possible, but you’d need to delve further into the Velocity templates.

    Here’s the overview and some pointers to more information on Velocity:

    http://confluence.atlassian.com/display/DOC/Velocity+Template+Overview

    Let me know if you find a solution :)
    Sarah

  8. Sarah,

    Thanks for the great information. I’m in the midst of choosing a wiki and planning the documentation. Any tips on translation once the documentation is in a wiki?

    Thanks.

  9. Hallo Bruce

    If it’s Confluence you’re using, then there’s a fair bit of support for other languages. The default Confluence installation comes with English, French and German — you can choose a language via the Administration Console.

    There are also a number of other languages available as plugins, which you can install onto your Confluence site. Here’s some information:

    http://confluence.atlassian.com/display/DISC/Language+Pack+Translations

    Here’s some information on Atlassian’s translation support in general:

    http://confluence.atlassian.com/display/TRANSLATION/Atlassian+Translations

    And if you’d like to develop your own language plugin, if there isn’t one already for the language you need, then here are the instructions:

    http://confluence.atlassian.com/display/DOC/Language+Pack+Plugins

    I hope that helps :)

  10. Hey Sarah

    Great info!! Im a tech writer too with around 5.7 yrs exp. in documentation. I would aprpeciate it if you could give me idea for writing blogs or wiks.

    Is there any major difference between blogs and wikis? Lemme know

    Regds

  11. Hallo PS
    Interesting question :) I guess there are two major differences between a blog and a wiki:

    * A blog post is like a news item — it’s aimed at a specific period of time, and is filed principally by date. You can add labels or tags, to group your blog posts into categories. But basically, people read your blog post at around the date of posting and then it kind of dies away. People subscribe to your blog so that they can keep up to date. They can find your previous blog posts by Google etc, but that’s not the main aim. In contrast, a wiki page is more like a repository of knowledge. Wikis often allow different structured ways of presenting information, such as in a page hierarchy or whatever. It’s a more permanent knowledge repository. You’d quite often go back and update a wiki page, but not a blog post.

    * The other difference is that a blog is primarily a personal thing. There’s the blogger and she’s supreme :) Whereas a wiki is for collaboration. Many different authors will add and update pages in the wiki.

    How’s that for an answer. Any more comments from anyone else?

  12. I leave in Australia, and i am in Cellege.
    I have been asked in my assignment as follow:
    find two different examples of technical documentionfor a computer system.

    I was looking for it until i come to your site.
    please i am still not getting what i was after.

    thank you.

  13. Hallo Chol
    There are a number of examples of technical documentation on the web. Here are two which you may find interesting:

    1) http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home

    This is the technical documentation for a wiki system. The wiki system is called Confluence. (Another famous wiki system is MediaWiki, and Wikipedia is a specific example of MediaWiki.) But going back to Confluence: The link above shows you the Administration Guide, User Guide, Installation Guide etc for the Confluence wiki. The interesting thing about this documentation is that it is hosted on an instance of Confluence. So in other words, the Confluence documentation is itself hosted on an instance of Confluence. Using a wiki for technical documentation is a fairly new and challenging development.

    2) http://code.google.com/apis/gdata/overview.html

    The above link points to Google’s API documentation. This is highly technical documentation, for developers who want to write programs that interface with Google systems. “API” stands for “application programming interface”.

    Good luck with your assignment :)

  14. Hi there,

    I’m a tech author for an ecommerce provider and we find that we have many authors contributing to our library of information (from sales and marketing to account managers to the development and technical teams) so a WIKI would certainly seem to fulfil our needs.
    However, I would like to know whether a there are any ways in which we can use the articles in a WIKI to produce traditional (book-type) user guides.
    In other words, is it possible to create a traditional user guide that would be fit for print purposes out of self-contained WIKI pages?

  15. Hallo Gavin

    Wow, that sounds like an ideal application for a wiki. Confluence, the wiki I’m using, allows you to create a PDF version of your documents. You can “export a space” to PDF (or HTML). A space is a set of pages within the wiki. You can also select an arbitrary set of pages for export, if you don’t want the entire space.

    The PDF export is not enormously sophisticated right now ;) but there are plans to improve it. And if you’re technically inclined, you can customise it yourself.

    Let me know if you’d like more information.

    Cheers
    Sarah

  1. Pingback: Foul Writer’s World - Questionmark joins the blogosphere and updates its wiki

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,508 other followers

%d bloggers like this: