As a technical writer, I love learning new tools. In this case, I’m implementing a pilot project using a Confluence wiki.
Until now, all our technical documents have been Word and CHM help files. And we’ve delivered these to our customers as links on a static web page.
This method made it easy for lots of folks to contribute to the documentation, but it also had a number of downsides. These were the things I wanted to address if we changed to a different system:
- Global searching across all documents
- Enterprise-level security
- Automatic update notifications or feeds
- A more efficient process
After a lot of research, Confluence seemed like the answer.
Yesterday I downloaded the latest evaluation version (Confluence 3.4). Our IT group is installing it on a server, but in the meantime I’ve installed it on my desktop, using the simplest settings, to get it up and running as quickly as possible. Once it was installed, I wanted to dive in. (Why is it that technical writers are so reluctant to read the tutorials first?) Anyway, without further ado, here are my first impressions:
1. Create a new space.
Easy! On the Dashboard, click Add Space. Give your space a name and a keyword, and click OK.
2. Change the layout.
Click Browse, Space Admin, then Themes. This can be as simple or as complicated as you want to make it. I chose to use the built-in Documentation theme, because I like to have the tree navigation on the left side of the screen. But eventually I’ll probably want to use the Adaptavist Theme Builder for a customized theme that matches the look and feel of the corporate website.
3. Add pages.
In your new space, click Add, and then Page. Give your page a unique name, and click Save. The unique name of the page is critical, and I’ll come back to this later.
4. Add content.
On your new page, click Edit. By default, you are on the Rich Text tab. You can start typing, add links and images, or you can click Insert to add macros to your page. Macros include things like a column layout or a mini table of contents. If you’re like me and you want to see the code view, click on the Wiki Markup tab. If you know which macros you want to include, it can be quicker to just type them here rather than going through the menu on the Rich Text tab.
5. Add attachments.
I figured the fastest way to add content to my new wiki would be by adding links to existing Word documents. That seemed straightforward.
On your new page, type the name of the file you want to link to (or whatever text makes sense), select it, click the Link icon, click Attachments, then browse for your file.
But I have so many files to add! There must be a faster way to add attachments. And sure enough there is. With the page not in Edit mode, click Tools, Attachments. With Google Gears installed, you can drag and drop files onto the page.
Everything worked great, until one file gave me an error – it was too large! After some searching I discovered there is a way to increase the size of acceptable attachments, but keep this in mind when you start out. The default setting is 5mb.
6. Import a Word file.
My initial plan is to replicate our existing static web page, but in the long term, I’d like the content to be written on the wiki. This makes it easier to update and much more efficient. But it means getting the content from the Word documents into wiki format. I decided to try out the built-in Word document importer (Tools, Import Word Document). Initially I chose not to split the document, so the entire thing was on a single wiki page. Once I added a Pagetree macro, to create a mini table of contents at the top of the page, this was acceptable. But I thought it would be better if I split the document into sections.
Remember what I said earlier about page names being unique? Well in our Release Notes, we structure the document by product modules, and each module contains sections for Enhancements and Corrections. In a wiki, depending on how I split the document, all these headings that are the same, have to have unique file names. For now, I’ve decided to split the document at the module level, but what this highlights for me, is that I can’t just import our current hierarchy into the wiki. We’ll need to consider our structure before moving forward.
The next step is to meet with the stakeholders to talk about exactly what we want to accomplish with the pilot project. Whichever structure we choose, we’ll have global searching – check that off the list! Tomorrow I’ll investigate the security and feeds to see how they work.
Are you using Confluence or another wiki for documentation for an enterprise application? I’d love to hear your experiences and suggestions in the comments.
Photo via Flickr user Jason Pratt