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:
- The editor’s introduction by Sue Woolley.
- A foreword by Geoffrey Marnell about the recent ASTC and PLAIN conference, a joint event in Sydney organised by the ASTC and the Plain English movement
Posted on 21 November 2009, in atlassian, Confluence, technical writing, wiki and tagged Confluence, documentation, technical documentation, technical writing, wiki. Bookmark the permalink. 9 Comments.
ffeathers 
Do you know where one can find scholarly accounts of what happens when technical documentation in wikis is used?
Hallo Milan
A while ago, I came across this article by The Synthetic Librarian: Good Wikis are not just for Collaboration, they Organize Knowledge. I hope it fits the bill. It’s not really about the usage of the wiki, but I think it’s an excellent and scholarly article. It’s a thorough analysis of MediaWiki by an academic who decided to install and evaluate a wiki, and chose MediaWiki as his guinea pig
Cheers
Sarah
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
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.
Thanks!
Hallo Mark
It sounds as if the “Ad Hoc Workflows” plugin will be ideal for you. It’s a Confluence add-on, developed by a company called Comalatech. They’re an Atlassian partner. I’ve met them a couple of times, and communicated with them quite a few times — great guys and a very useful and popular plugin.
Here’s a link to their website:
http://www.adhocworkflows.com/display/WWW/Home
Here are the details on the Atlassian Plugin Exchange:
https://plugins.atlassian.com/plugin/details/142
Roberto from Comalatech recently wrote a blog post that may be interesting. It’s not about your use case, but does give good insight into the flexibility of the plugin:
http://blogs.atlassian.com/confluence/2010/08/enterprise-wiki-workflow-publishing-knowledge-base-article.html
That sounds like an interesting set of documentation and a very rewarding collaboration and feedback scenario! Let me know if you blog about it or write any online reports or articles. I’d love to know how it goes.
Cheers
Sarah
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
Pingback: How technical writers can make themselves heard « ffeathers — a technical writer’s blog