Using a wiki for online help
Online help — it’s a technical writer’s dream. We all want to design and write online help systems, and we all know that context-sensitive help is the way to go. Can you do it on a wiki?
Yes 🙂 I wrote an article on the Atlassian News site this week, illustrating how we’ve used our Confluence wiki to provide context-sensitive help in the latest FishEye and Crucible software releases. Have a read. It’s got some pretty pictures as well as the technical stuff 😉
Clarifying my terminology: By ‘context-sensitive help’, I mean that when you click a help link on an application screen, you get the instructions directly related to that particular screen. Also at a deeper level, when you click a help icon next to a field you get help on that specific field. We’ve provided both these levels of help, as described in the above article. Another type of contextual help is when you hover your mouse over a field and a short description pops up in a kind of bubble. That’s usually called a ‘tool tip’, and is not what I mean here.
I’ve written a number of online help systems for various companies, using a variety of tools. My favourites were Help and Manual and RoboHelp. I’ve also dabbled with HDK (the precursor to XDK) and with Microsoft’s ‘raw’ HTML Help editor. And now I’m using Confluence wiki.
What’s the difference between a wiki and a help authoring tool? Well, there’s a big difference, of course. A wiki is essentially a collaboration platform — your online documents become a place where everyone goes to find information, share their own tips with others, and pick up the latest updates. A help authoring tool is tailored towards building a documentation set which is essentially static (even if you update it every day, it’s still not a discussion platform) but which has all the bells and whistles of an integrated online help system.
Most help authoring tools provide the following functions. You’ll probably have trouble finding a wiki which supplies these functions to the same degree:
- Fully customisable table of contents, where you can put topics in the order you want, omit topics, or make a single topic appear more than once.
- Integrated keyword index.
- Integrated glossary.
- Navigational tools to make topic browsing easier, such as the ‘browse sequences’ provided by RoboHelp.
- Topic linkage tools, such as the ‘next topic’, ‘previous topic’ and ‘related topics’ tools which are built into some help authoring tools.
- Generation of HTML Help (.chm) and WinHelp output files.
- Workflow support (draft, review, publish).
- Integration with a source control tool such as VSS, or RoboHelp’s inbuilt check-in check-out manager.
- Automatic generation of topic IDs, which you can hand over to a developer for plugging into the code to generate context-sensitive help links.
- Sophisticated topic templates.
That’s a long list. So what does a wiki provide, in terms of usefulness for online help?
- A wiki page is just a URL — so you can link to the page directly from your application screen. (Read my Atlassian News blog to see how we’re doing it with Confluence.)
- Wiki pages are continuously being updated and enhanced by technical writers, support staff and even customers who have useful tips to share. So when someone clicks the help link, they get the most up-to-the minute information possible.
- Wikis allow you to embed multimedia goodies such as images and Flash movies.
- You should be able to generate PDF, HTML and XML versions of your wiki pages.
- A good wiki has a good search engine.
- Some wikis provide version control — all changes are tracked, and you can see who made each change or even revert to a previous version of a page.
- A wiki often provides tools for runtime integration with other software — many wikis allow you to install plugins or addons which display information directly from another platform. For example, a wiki page can show a list of bug fixes drawn dynamically from an issue tracking system like JIRA.
- Some wikis allow blogging as part of the wiki platform. So your documentation page can embed a list of the latest blog posts related to the topic of the page. The blog posts will always be the most recent as at the time the user views the wiki page.
- Your wiki is sure to have a number of other interesting features which you can use to work around some of the shortfalls listed above. If you’re interested, take a look at my previous posts on using wikis for technical documentation.
In short, wikis are different. They’re not necessarily better or worse — it depends what you need for your documentation system. Wikis are fairly new, so they’re developing all the time. I’m having fun riding the wave 🙂
Posted on 15 December 2007, in atlassian, Confluence, online help, technical writing, wiki and tagged atlassian, Confluence, contextual help, documentation, help authoring tools, online help, technical documentation, technical writing, wiki, wikis. Bookmark the permalink. 4 Comments.
ffeathers 
I’ve authored primarily using RoboHelp in the past, for security concerns my current company uses Mac OS X only. I’m currently using Word to create our user documentation. Up to now it’s been a reasonable compromise, however our company and product range is expanding rapidly and I’m in need of a single source solution, such as RoboHelp. Along with this, we’re entering the international markets, which means localization and skinning. It’s no longer practical editing these documents using Word. I’d love nothing more than to use the industry leading apps such as RoboHelp or Flare, however they’re both Windows only, as with many other decent HAT’s out there.
We’re about to deploy a company Wiki (Confluence) – I’ve read articles that this can be used as an authoring tool. I haven’t seen this in action though and I’m not sure how this would handle content re-use, localization and skinning etc. I really need something that is topic based, database orientated, has tags, snippets and a system to apply various custom css for skinning.
I’ve thought of DITA and this seems the most practical solution as it’s supported by the OS X, the two that come to mind are oxygen XML Author and XMLmind XML Editor. I’ve used XMLmind in the past and found it to be effective. Could I leverage a similar degree of flexibility from confluence as one of these purpose built HATs?
Unfortunately I cannot install and trial various applications at work as it requires a complex and time consuming vulnerability analysis. I’ll probably give it a whirl at home, however as you have used RoboHelp, my favourite authoring tool – how close does Confluence come to this in terms of what we need as tech writers? You feedback would be valued and appreciated.
Hallo Andrew
Phew, that’s a large number of questions all in one go. 🙂 The thing about a wiki is that it’s a completely different tool from the HATs we are used to working on. A wiki is engineered for collaboration and team work, where the word “team” can mean a large number of people. For that reason, moving to a wiki does involve a change in processes and team focus.
That said, when I moved to a wiki it was like a breath of fresh air. In my opinion, and in the type of environment that I’ve worked in most, the open and collaborative way of doing things leads to faster production of better documentation.
Still, when choosing a wiki, as when choosing any tool, you will need to weigh up the pros and cons and decide what suits your requirements best. I guess that’s the reason for your list of questions. 🙂 I’ll address them one by one.
Skinning: You can apply different themes to Confluence. It ships with three themes. For more flexibility, you can install a plugin. It sounds as if you’ll need significant branding of your site. In that case, I’d recommend the Zen Foundation theme or the Refined Wiki theme, both of which are commercial plugins for Confluence.
You can find the various themes on the Atlassian Plugin Exchange:
https://plugins.atlassian.com/
Localisation: Bitvoodoo provides a plugin for this purpose: https://plugins.atlassian.com/plugins/ch.bitvoodoo.confluence.plugins.language
Single sourcing: In my opinion, it’s best to develop and publish the content on the wiki. But sometimes you may need to develop the documentation on Confluence and then export it to various formats, or develop it on some other tool (foregoing the collaborative aspects of the wiki to a great extent) and the import it into Confluence.
My slides from this webinar have guidelines on importing and exporting content:
Content reuse: Confluence provides macros that you can use to pull the content from one page into another page, dynamically at the time the page is rendered. The mechanism is not as flexible as in some authoring tools or DITA. Here’s a post that explains it and gives some guidelines on best practices:
Topic based: In Confluence, content is topic-based. Each page represents a topic. You can organise pages into hierarchies (tables of contents) and spaces (libraries). However, if you’re looking for a structured authoring environment such as DITA, a wiki does not provide that type of structure.
That said, the K15t Software team are busy developing a Scroll Wiki Forms plugin for Confluence that will impose a layer of structure over the wiki pages. When that plugin is mature, they intend to provide a DITA export too. (Importing from DITA is already possible.)
http://www.k15t.com/display/en/Scroll-Wiki-Forms-for-Confluence-Overview
In short, working on Confluence is nothing like working on RoboHelp. It’s overall a much simpler environment, leaving you free to focus on the content rather than the tool. But, like all tools, it has its own complexities. Since it’s not designed for technical documentation as the sole use case, you’ll find that there are nuisances and missing features that you’ll need to work around. On the other hand, you’ll find surprising new tools that you can make use of in interesting and innovative ways.
By the way, I hesitate to indulge in self-promotion, but I’m wondering if you know that I’ve recently published a book on developing technical documentation on Confluence? It probably has the answers to most of your questions. It’s called “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”. Here’s a page about it:
https://wikitechcomm.onconfluence.com/display/CHAT/About+the+book+-+Confluence%2C+Tech+Comm%2C+Chocolate
Good luck, and I hope I’ve helped!
Cheers
Sarah
“Hi,
I would have to agree with you on the fact that people do get confuse between a tooltip and context sensitive help. I have been writing context sensitive help for many applications and like you mentioned, I am living the dream. I generally use ProProfs.com Knowledgebase as my wiki solution in creating the context sensitive help articles. I also tried Mediawiki and other open source platforms but it didn’t work for me, probably because I prefer very easy to use interface. How is Confluence for creating wikis? Is it something different from other wiki solutions? “
Pingback: Wiki’s the Secret Word of the Day « Spacebar