Wow, what a week that was! After spending much of last week basking in the warm glow of the Unite event, this week was spent getting my hands dirty with the forum functionality and a CSS/browser-related issue.

Setting up a forum involves a degree of learning, and as we all know, there are three stages to learning:
1. Knowing you know nothing, but are faced with a mountain of information to absorb.
2. Feeling totally lost and bewildered as you try to understand what everything does and how make it work.
3. Wonder why it all seemed so stupefyingly difficult now that you know that it is, in fact, ridiculously simple.

I'm still at stage one with the forum.

Secret of Learning Revealed
Actually there's a fourth step that I often forget and no one readily admits to knowing. And that's called RTM (aka RTFM!) or Read The Manual. 

Which is very good advice that I, as a writer with 20 years of experience, should follow without even thinking about it. I suspect I'm not alone in forgetting. That said, there's a lot of enjoyment to be had from just diving in, and I find that the things I learn this way tend to stick more easily than the things I read about. 

User Conversations: I'm All Forum
We've told clients the forum would be available in early 2012, so there's some pressure to get it sorted asap. But this has to be balanced with any writing that has to be done, plus wiki support and training. So far I've only added the main forum macro, which actually does produce something that is useable, albeit very minimalist. 

Although you get a lot of wiki out of the box with Atlassian, there are dozens of companies around the world who build pluings that can be used in the wiki to extend is functionality. Some of these you have to pay for, but many are free. Adaptavist's Community Bubbles macros, which we're using to create the forum, are a part of the Essentials package, which is free and contains 19 plugins. 

One benefit of going to the Unite conference in London was meeting up with the Adaptavist staff, who very generously said I can call them when I need help. So far, they've lived up to their promise, but I'm only just getting started, so that might change.

One of the problems I've encountered with setting up the forum is that my expectations of what it should be were getting in the way of me seeing the forum in the way Adaptavist intended. At first it didn't make any sense, but by adding some new topics and replies, and the Make Sticky function, it  became easier to see how it works. It is getting clearer, but I'm still baffled to some extent. In the end I had to stop playing and work on some more pressing documentation and support tasks. I'll have another look this coming week and you never know, I might even read the manual. 

Rest assured, you'll be able to read about my success or failure here.

Delete My Cache
On top of that we had trouble hiding the Export to Word feature. Confluence can export to Word and PDF from the Tools menu (and also to XML and HTML from the Space Admin area) but I'm not happy with the Word formatting. It's ok, but that's about it. The PDFs are very good though. 

The main reason for disabling it is because when you create a PDF, it automatically includes a date and time stamp in the file name, so you know exactly when it was exported. The Word file doesn't.

Exporting a pretty useful thing to have because we clients to be able to print pages. However, we also want to make sure that when they do so, they know that, as far as we're concerned, the printout's content is considered to be out of date. We prefer people to use the latest version of our user information. And that means using what's in the wiki as of now.

The problem with printed material is that it can't be updated, so it becomes stale and possibly wrong (because software never stands still). 

If you use the current wiki content, then you know it's the latest version, whereas a print out could be weeks, months or even years old. 

Which is not a good thing: it can cause frustration and possibly end up with a call to support which shouldn't have been necessary. Far better to avoid that and use the most current content from the wiki.

But back to the problem. Our wiki is hosted by Clearvision, and their support team and I spent some time going back and forth trying to find out why it was that, having hidden the Export to Word function by editing the CSS, users could still see it.

After a lot of testing, we found that it was a browser cache issue. And to fix this means jumping through several technological hoops - which I won't even be asking colleagues to do, let alone clients. In the end I bumped the issue up to the IT Dept, who I hope will be able to resolve it asap.

So now our choices are either to leave the Export permissions set to null, or just let everyone use it despite my misgivings. 

Assuming the latter, our workaround will have be writing a How-To that explains how to run the export/print function and include a proviso about the shelf life of anything that is printed. Although I'm not
satisfied with this, what's more important is client satisfaction, so I can live with it.

As this is my first blog about using Atlassian's Confluence wiki as a technical author, I think a short explantion is required.

I've been working as a technical author for about 15 years, mainly in software but I've also worked in other areas such as hardware and OM document sets. My current role is with a British software house working in trading and risk management.

Three years ago we started using a wiki for all our client documentation as well as our intranet. Last year we acquired two other companies, both of whom used Confluence. After comparing the two systems we were using, we decided to use Confluence throughout the entire organisation. That done, we migrated our original wiki along with the two other Confluence instances into one brand new one. A great deal of thanks for the success of this project have to go to Clearvision, an Atlassian partner, who organised and oversaw the whole operation.

I firmly believe that Confluence is the way forward for technical documentation, and, having used wiki technology for three years now, I believe I have the 
experience and knowledge to back this up. I intend to do this in the coming months as I describe and share my experiences and insights gained.

But First, This!
Last Monday, the 12th March, I attended Atlassian's Unite conference in London. This not only gave me first hand access to various Atlassians, including Mike 
Cannon-Brookes (co-founder and CEO) but also to a huge number of people who are connected to Atlassian. They are connected because they are users like me, or are Atlassian partners. For example, Clearvision and Adaptavist.

The morning kicked off with a talk by Mike Cannon-Brookes that covered everything from it being Atlassian's 10th birthday (almost) to sending out their very first invoice, to where their tools are now and where they are heading. After that we got further insights from other Atlassians into Confluence and JIRA, which in my eyes are the core Atlassian products. What I really enjoyed about all this was the refreshingly straightforward way the company presents itself. It might be that they put their best face forward, but there is no BS here - something a lot of other businesses would do well to emulate.

Lunch looked excellent but I forsook the very long queue for it for a small salad. On the upside I managed to get myself a place at Mike's table (Atlassian had several tables manned by staff who were there to spit out advice and information between mouthfulls of lunch). Our conversation ranged from the enormous size of Australia, to the un-helpfullness of the weather, to promoting the use of Atlassian products to colleagues and senior management. It was refreshing to hear a CEO straight-talking instead of spinning and weaving.

The afternoon continued with a couple more talks about JIRA and building the Atlassian community in the UK, featured demos from a variety of clients that covered how they used Atlassian's products in their production systems, and gave insights into how they promoted the use of the technology to staff. This is something I'm keen to know more about as part of my role is to be the wiki evangelist, and although most people see the benefits as soon as they start using the software, there are a few you have to use velvet thumbscrews on.
Also, you might expect these talks to be primarily from software and technology businesses, which is true, but in fact manufacturing industries also use Atlassian's products. For example, we were treated to a lively talk from the world's second largest pump manufacturer in the shape of Ole Kristensen, the lead consultant at Grundfos.

The day ended with everyone hot-footing it to a nearby bar for refreshments and even more conversation, free food and business card collecting. Which demonstrates another thing Atlassian is very good at: community building - which is almost the primary function of all their products. Obviously, on such an occasion, you can't talk to everybody, but you can target a few people and build more personal relationships with them. For instance, I built on my existing relationship with Clearvision and various members of Atlassian's support teams, and launched a new one with Adaptavist. This resulted in getting 
some very heplful insights into using their Community Bubbles plugin, (which we're using to build our client forum) plus the promise of some free support when I start setting it up.
All in all it was an excellent day and money well spent: I went home full of useful information, fired up with the knowledge I'd gained, and very pleased with the opportunities for various collaborations that had arrisen during the day and evening.
Now all I have to do is write up my nine pages of notes for my management report, fill in my expenses claim, and get the forum set up and working: life as a 
technical author will never be dull again.

And Now For Something Completely Different
As of next week, my blog will focus more on how I use Confluence for technical writing and related matters. This means promoting the wiki and its usage to colleagues, technological issues, developing the wiki (structurally and functionally) support issues etc etc. Please feel free to comment and share your thoughts and ideas.