Can you use a wiki for online help? And what are the tricky bits that you might need to work around?
Atlassian’s technical documentation is online, alive, and version-specific. Most of it is written, managed and hosted on our Confluence site. Being a wiki, this site is a hive of activity – we are constantly updating and enhancing the pages, and visitors to the site add useful comments day and night.
Can this possibly be the right environment for context-sensitive help links – can we point a link from the screen in one of our shipped software products directly into a living and thriving wiki page?
We’ve done it already
The latest Fisheye and Crucible releases have help links on the application screens, pointing directly to the corresponding documentation page on our Confluence site.
Help is just one click away. Look at the above screen as an example. When a Fisheye administrator clicks the ‘?’ icon next to ‘Mail Server’, a new browser window or tab opens showing the guidelines on configuring an SMTP server:
The instructions, illustrated above, come directly from the wiki pages – the information is up to date, to the minute.
How did we make it happen?
When we are designing the documentation and the application itself, the technical writers and the developers work closely together. We decide where the help links are needed on the application screens, and structure the documentation pages carefully so that there is a good ‘landing place’ for each help link.
The job doesn’t end there. On an ongoing basis, the technical writers make sure that the documentation is updated and enhanced with the latest information. We also manage the documentation’s release dependencies, so that there is a separate and complete set of documents for each major release of the application (Fisheye 1.3, 1.4, etc).
The tricky bits
But what if we need to change the name of a page – does this break the online help link, because the page name is embedded into the wiki URL?
The Fisheye and Crucible help links do not contain hard-coded URLs. Instead, we use a file called ‘help-paths.properties’, which maps each help link to the corresponding page name. The technical writers do take care not to change page names unless absolutely necessary, and we make sure that any changes coincide with a new release of the product.
Here’s a snippet from the ‘help-paths.properties’ file, including the bit that maps the above ‘Mail Server’ help link to its corresponding ‘SMTP’ documentation page:
## Documentation roots
fisheye.help.url.prefix = http://docs.atlassian.com/fisheye/docs-014
crucible.help.url.prefix = http://docs.atlassian.com/crucible/docs-012
## Default help pages
fisheye.default.help.key = Fisheye+Documentation+Home
crucible.default.help.key = Crucible+Documentation+Home
## …
## Fisheye Administrator’s Guide
# 4. Setting up your Web Server
fisheye.web.server.settting.up = 4.+Setting+up+your+Web+Server
fisheye.web.server.config = Configuring+the+Fisheye+Web+Server
# 5. Configuring SMTP
fisheye.smtp.config = 5.+Configuring+SMTP
## …
OK, now what happens when the documentation has moved on to a later release? For example, you may be using Fisheye 1.4 when the documentation has already been upgraded to suit a later version some time in the future. You don’t want to see instructions for the wrong Fisheye version.
The technical writers make sure that there’s a discrete set of documentation for each major release. For Fisheye, at time of writing this blog post, there’s a Confluence space for Fisheye 1.3 and another for Fisheye 1.4. We call the Fisheye 1.3 space an ‘archive’ space, because it relates to a previous version of the software. And we call the Fisheye 1.4 space the ‘main’ space, because it always relates to the most recently-released version of the software.
At some time in the future, we’ll release a new version of Fisheye. Then the main Fisheye space will be updated for the new release, and we’ll move the Fisheye 1.4 documents to a new archive space.
How does the help link find its way to the right space? From Fisheye 1.4 and Crucible 1.2 onwards, the applications are clever enough to find the correct release-specific documentation on the Confluence wiki. The developers have created a ‘.htaccess’ file to redirect the incoming requests to the relevant Confluence space.
A ‘.htaccess’ file is a directory-level configuration file which you can put onto an Apache web server. You can do various things with such a file – read the Apache documentation for more information. We use ours to rewrite the URL:
- All the help links in Fisheye 1.4 look something like this: http://docs.atlassian.com/fisheye/docs-014/Fisheye+Documentation+Home.
- When a user clicks on a help link, they are sent first to docs.atlassian.com, then redirected to the release-dependent documentation space on the Confluence site.
Here’s the content of our Fisheye .htaccess file:
RewriteEngine on
# eg docs.atlassian.com/fisheye/docs-014/Fisheye+Documentation+Home
RewriteRule ^/?docs-014/(.*)$ http://confluence.atlassian.com/display/FISHEYE/$1 [L]
RewriteRule ^/?docs-(d+)/(.*)$ http://confluence.atlassian.com/display/FISHEYE$1/$2 [L]
It works and we like it
We’re planning to implement something similar for more of the Atlassian products soon. Wiki while you wait 😉