Davidson Media

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 RevealedActually 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 ForumWe'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. Sofar 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 CacheOn 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 notsatisfied with this, what's more important is client satisfaction, so I can live with it.

Which is very good advice that I, as a writer with 20 years of experience, should follow without even thinking about it."

I believe that this says more about how manual content is presented than a lack of williness to RTM. I, too, am jaded because I want to understand the produce that I just bought and how it works, but find that manuals spend more time on the mundane and not on what I need to get going on using the product. Isn't this content presentation what the "wiki as documentation" suppose to improve? Was the manual you were suppose to read a wiki? Or is the forum app not a confluence user?

BTW
"Some of these you have to pay for, but many are free. Adaptavist's Community Bubbles macros, which we're suing to create the forum,"

I know us Yanks are litegious, but now so much the British. I think you meant 'using', not 'suing'.

I look forward to your posts, and having you experience all the pain while I learn.

Reply

mick

3/25/2012

Lew,
Thanks for taking the time to respond.

Not reading the manual is entirely down to me - I like to through myself in and see what I can learn from experience and clicking around. I also find that if I familiarise myself with something, even if I don't fully understand it, this helps when I start reading the manual. For example, I'm better prepared for new terminology and concepts.

I have read a little of Adaptavist's info and it seems pretty well written, so if there's anyone at fault here it's me and the way I go about things with software. If this were a new electronic gadget, unless it was ridiculously simple, I'd always read the instructions first.

Leave a Reply.

About the Blog

Hello and welcome to my blog on using wikis for technical authoring. Published weekly, it focuses on my experiences using Atlassian's Confluence wiki, though I may get sidetracked. I've been using Confluence for over ten months now, so the information and tips you'll read here are for those who have little or no experience of it. I've been using wikis for technical documentation for three years.These are my personal opinions: I am not connected to Atlassian in any way other than using their products.Feel free to comment and share your ideas.What's a Wiki?A wiki is a web-based knowledge base populated with content that can be text, graphics, charts, videos etc. One of is key features is that it allows users to collaborate on tasks such as technical writing and development projects.

LinksYou can find more Atlassian experts and products by following these links.