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 ;)

Out of the box, Confluence is beaut. Add a plugin or two, and your documents glow. So which plugins do we use in the Atlassian product documentation?

Here at Atlassian, we use a wiki for almost all our product documentation. On our Confluence site, you'll find user guides, administration guides and other technical documentation for Bamboo, Clover, Crowd, Crucible, FishEye and of course for Confluence itself.

* Quick quiz: Which product is missing? Answer is at the bottom of this blog.

To add extra structure and style to our documentation, we use the macros provided by some Confluence plugins. We limit ourselves to just a few plugins, because we're aware that many customers download our documentation in XML format and upload it into their own Confluence installations. And they don't necessarily have the same plugins installed as we do.

Giving it some structure

The question we're asked most often is this:

How do you get that dynamic table of contents in the left-hand panel?

We've inserted the pagetree and pagetreesearch macros into the page layout for most of the documentation spaces. You can find some guidelines here. Below is an example. (Click the image to open an expanded view, and click the link below the image to go to the documentation page itself.)

Example 1
View the real page.

The {pagetree} macro generates the table of contents on the left. It shows the pages in the space, starting from a given level in the page hierarchy.

We use {pagetreesearch} to confine the search results to a space, or even a lower-down hierarchy of pages. This is great when you have a large Confluence instance, where the search results can be a bit overwhelming.

The toc macro (see example 2 below) generates a table of contents from the headings on a single page. You can limit it to show only a given level of headings. In our release notes, we've used {toc:minLevel=2|maxLevel=2}. So we can use the 'h1' level of heading as a section break, without it appearing in the table of contents. In the example below, 'Highlights of Confluence 2.6' is a level-1 heading and 'Fresh look for the Default theme' is the first of the level-2 headings.

Example 2
View the real page.

To show 'related topics' and mini tables of contents, we use the children macro (not illustrated here) and the contentbylabel macro (see example 3 below). We find the {children} macro useful for a carefully-structured hierarchy of documents, whereas {contentbylabel} is handy for a more loosely-associated set of pages such as FAQs and 'related topics'.

Example 3
View the real page.

To repeat information on more than one page, such as introductions and overviews, try excerpt-include and include. (Not illustrated here.)

Making it look good

Confluence allows you to upload and display ready-made images and photographs. In addition, you can create and edit images and diagrams within Confluence itself, using the Gliffy plugin. Here's an example:

Example 4
View the real page.

To make a note stand out from the rest of the page, we've enclosed it in a panel and made it float to the right of the page. See example 5 below. The {float} macro is part of the Composition plugin.

Example 5
View the real page.

The section and column macros give our pages some structural style. You can see them in action in examples 1 and 2 above. For other pretty layout effects and emphasis, try note, warning, tip (see example 3 above) and info. To preserve formatting in code and other extracts, we use code and noformat. (Not illustrated here.)

Archiving documents and managing releases

We provide a separate set of documentation for each major release of a product. For example, the current Bamboo space contains documentation relating to the most recent Bamboo release. And there is an archive space for Bamboo 1.1.

To create the archive copies of the spaces, we use the Copy Space plugin (still in a beta release).

More about macros and plugins

• Plugins are add-ons to Confluence. Some plugins are pre-installed in Confluence. Your Confluence administrator can decide whether to install others.
• A plugin may allow you to use one or more macros on your Confluence pages. (More about using macros).
• Take a look at the full list of Confluence plugins and the documentation for each of them.
• To see which macros a plugin contains, administrators can go to the Plugin Repository on your Confluence instance and click the plus sign under the plugin name. The Plugin Repository page will also tell you whether the plugin is installed on your version of Confluence.
• Not all plugins are officially supported by Atlassian. Refer to each plugin's documentation page in the plugin list for information about its status. The macros shipped with Confluence are listed in the Confluence User Guide.
• Tip: To see the macros and other markup which generates a specific wiki page, go the 'Info' tab of the page and click the 'View Source' link near the top right of the tab.

* Answer to the quick quiz: JIRA, of course. The JIRA documentation is housed in Apache Forrest at the moment. We plan to move the documentation to the wiki soon.