Article about Confluence wiki for technical documentation

My article on “Using a wiki for technical documentation” appears in the October edition of Southern Communicator, the Australian and New Zealand journal of technical communication. Exciting!

A big thank you to Janet Taylor and the journal’s editorial team, both for inviting me to contribute and for allowing me to publish a PDF extract of the journal on this blog. Another big thank you to Marian Newell, who kindly gave permission for me to include her article here too. You guys are stars!

Click this link to download the PDF file containing the journal extract. Below is a summary of the content.

Using a wiki for technical documentation

My article is on pages 6-10 of the PDF file. (Printed page numbers are 4-8.) It covers the following topics:

  • Overview — what a wiki is and does.
  • Workflow — draft, review, publish.
  • Tracking — page history, notification of updates, reverting to a previous version.
  • Permissions.
  • Adding structure to your documentation — table of contents, left-hand navigation bar, logical page ordering, content re-use.
  • Release management.
  • Agile development methodology.

(The article is based on my earlier presentation of the same name. You may find the slides and screenshots a useful adjunct to the printed article, since the images are rather small in the article.)

Trends in British technical communication

The journal’s editorial team allowed me choose another article from the journal to include in the PDF extract. I chose Marian Newell‘s very interesting article, “Trends in British Technical Communication”. She discusses a number of topics, including:

  • Our job titles — Are we technical writers, technical communicators, technical authors, content creators…? Personally, I prefer to be known as a technical writer. But read what Marian has to say.
  • Deliverables and workplaces — printed or online content, large long-lasting projects or smaller shorter projects.
  • Tools and methods.
  • Generalisation and specialisation.
  • Translation.
  • Fads and fashions — user-generated content, social networks, information facilitators, modular content.
  • Quality and productivity — Is “good enough” good enough? Should we obtain a standard qualification to put us on a par with other professions?
  • Economic and commercial factors — global economic crisis, current demand, freelances and agencies, outsourcing, offshoring, remuneration, standards of written English.

And more

The PDF file also includes:

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 21 November 2009, in atlassian, Confluence, technical writing, wiki and tagged , , , , . Bookmark the permalink. 9 Comments.

  1. Do you know where one can find scholarly accounts of what happens when technical documentation in wikis is used?

  2. Sarah, I really enjoyed your article. I just found out this morning that I’ll be able to use Confluence for some of our documentation. I’m quite excited about it.

    • Hallo Tom
      That’s great news! I’m quite excited on your behalf too. 😉 Let me know how it goes, and please feel free to contact me if you have any questions.
      Cheers, Sarah

  3. Hi Sarah,

    I enjoyed your article, you’ll be glad to know it is still being read nearly a year since it first came out…

    I have a situation that is similar, involving technical documentation, but includes a slightly different angle.

    Once the documentation is written it will be made available for hundreds of users, blue-collar guys who are working on the floor, but who need to be able to refer to the information. Legacy systems show that these users often have good input as well, sometimes machines get upgraded or changed, or OH&S steps in, or all sorts of things. In these cases the documentation relies on feedback.

    What I need is to be able to apply something similar to what you describe in the ‘Workflow’ section, but where, instead of dealing with a new page, the workflow applies to an edited draft which, until approved, can not be seen by the regular users who continue to see the pre-edit version of the page.

    Does this make sense? Do you have any advice? I have installed a development version of Confluence on a server and am trying to extract this particular functionality from it.


  4. Sarah –

    We are looking at moving our product documentation to a wiki and are currently running a demo using Confluence. While its a great product there is one aspect of this project that seems to not be solved well with Confluence – multilingual support.

    The UI of our product is available in almost 30 languages and we will need to have product documentation available in at least the 10 most common languages (English, Spanish, French, etc.).

    How does Atlassian handle the need to internationalize its product documentation or how do your larger customers manage this process.

    At present I keep coming back to a separate space per language which I then have to copy each time I make a release of our product. So that is 15+ spaces for each product update/release and we typically do that 2-3 times per year … ouch.

    Any suggestions?

    • Hallo Michael
      That’s a good question, and one we haven’t completely solved yet. We at Atlassian don’t (yet) provide translations of out documentation. The solution you suggest, of using a separate space for each language, is the one we always recommend.

      This requirement is something that interests me very much. I also think the time is nigh when we ourselves will need to provide translations of the docs, and thus will need to design, develop and release a wiki solution. If you have any ideas, I’d love to hear them.

      Gina is also looking into a solution. Here’s her latest blog post about it.

      Cheers, Sarah

  1. Pingback: How technical writers can make themselves heard « ffeathers — a technical writer’s blog

Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s

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

%d bloggers like this: