Recording of webinar about Confluence wiki as documentation platform

On Thursday I was a co-presenter in a webinar about Confluence wiki as a platform for technical documentation. The recording of the webinar is now available, as well as my slides, and a wiki page for discussion and questions.

The recording

The video is available on YouTube:

The slides with speaker’s notes

The slides for my part of the webinar are available on SlideShare: Confluence as a platform for technical documentation.

To see the speaker’s notes, click the tab labelled “Notes on slide n” under each slide (next to the comments tab).

Wiki page for discussion and questions

The recording, slides and other information are also on a page on the Atlassian documentation wiki: Confluence as a Platform for Technical Documentation Webinar. Drop in there to see what people are saying.

Congratulations to the prize winners!

Twelve lucky attendees won prizes in a draw after the webinar. Congratulations all! The names of the winners are announced in an Atlassian blog post.

Webinar includes sneak previews of new wiki tech comm products

For an overview of the three sessions in the webinar, take a look at my earlier post: Invitation to join me in webinar about Confluence and technical documentation.

Just to entice you, here are a couple of hints about what my co-presenters talked about and demonstrated during the webinar. 🙂

Tobias Anstett from K15t Software talked about his company’s vision that wiki technology is the future of technical documentation. He gave two demos of the Scroll DocBook Exporter and the Scroll EPUB Exporter, which you can use to convert Confluence content to DocBook XML and EPUB formats. Tobias also hinted tantalisingly that K15t Software will announce two new products at Atlassian Summit in May. The two products focus on the planning, creation and quality assurance parts of the documentation life cycle. There’s also a solution in the works for wiki-based online help, including the ability to add user comments. Exciting!

Darryl Duke from Stepstone Technologies demonstrated the Zen Foundation theme. I loved his point that collaboration is and always will be about human interaction. So, to get people to use a wiki, familiarity and visual integration are very important. People need to feel that they belong on the wiki. The wiki must be a high quality reflection of the community and brand that it serves. With the Zen theme, you can produce a very sophisticated look for your wiki site. Zen also customises the wiki editor. Darryl gave a very cool demo of how you can drag and drop sections of a page, edit a section as an independent block of content, and use master pages to define standard page layouts. He then gave us a sneak peek of a new interactive brand designer that Stepstone Technologies will launch at Atlassian Summit in May. (In the Zen theme, the brand is the collection of CSS and images that determine the look and feel of your site.) Very smooth indeed!

What’s it like presenting a session in a webinar?

At the beginning of this post, I wrote that the webinar took place on Thursday. Actually, it was 1 a.m. on Friday morning here in Sydney! It felt a bit odd, sitting all alone and  speaking into the ether at 1 a.m, hoping that people were listening. It was great when I saw all the questions flooding in, and knew that people really were there. The webinar hosts later told me that more than 200 people attended. That’s so cool.

One tip I’d give to people who are planning to take part in a webinar: Practise beforehand. You’ll need to play with the webinar software, and to run through your presentation. The software is fairly easy to work with, so one practice session is enough to get to grips with that.

Running through your presentation is even more crucial. I’d recommend doing the run through at least twice. Also, do it in the same place and if possible at the same time as the real event. Speak your presentation out loud. You’ll feel like a banana (in other words, a bit silly) but it’s better to feel that way when you’re practising than during the actual event. Why should your practice session be at the same time as the actual event? It helps you to identify any possible hazards, such as loud noises or the need for an extra light. In my case, I decided to hold my practice session during the day time instead of at 1 a.m. As a result, I didn’t realise how dark it would be in the room where I was huddled at the bottom of the house, trying not to wake everyone else. So I had to rush around looking for an extra light just before the webinar started!

Doing the webinar was interesting and fun. Thanks so much to everyone for attending, and to Terrence and Matt at Atlassian for holding everything together behind the scenes. And congratulations to Tobias and Darryl on their excellent presentations. Co-presenting is the way to go!

Confluence tip – HTTP 500 or 504 error with Copy Space plugin

This tip is for people using the Copy Space plugin on Confluence wiki. If you’re copying a large space, you may see an HTTP 500 or HTTP 504 server error a few minutes after starting the space copy. Don’t panic. It’s likely that the copy process is still going on. Whatever you do, don’t close the browser tab or window until you know for sure.

It happens to me often, and it happened in a rather spectacular fashion earlier this week. I’m letting you know, in the hope that I can save you from a moment of panic. Or, as in my case this week, from a few hours of unnecessary frenzy.

About the HTTP 500 and HTTP 504 errors

When you get an HTTP 500 error, your browser window displays a message something like this:

• 500 Internal Server Error
• Internal Server Error
• HTTP Error 500

The error message is a bit useless. It doesn’t give you much information, and it sounds very dire. Basically, it means that something has gone wrong and the server can’t give you more information. This is the error we get when using the Copy Space plugin on our production documentation wiki.

I’ve also seen an HTTP 504 error appearing in the same situation on a test server. It seems that the server configuration determines which error you get. HTTP 504 is a Gateway Timeout error. That’s a bit more helpful and a little less scary.

What to do if you get an HTTP 500 or 504 while copying a space

First, wait a while. It is most likely that the front end has timed out, but the copy process is still happening in the background. Do not close down your browser.

Open another browser window or tab, and try going to the address of your new space. The space will become available when the copy operation has finished. Keep trying.

How long should you wait? Ah, now there’s the rub. The copy operation can take anything from a few minutes to a few hours, depending on the size of your space. Until this week, I would have said 2 hours was the maximum time to wait. This week, one of our spaces took 5 hours to copy. I guess the answer is: It depends on your previous experience with copying spaces on your wiki.

When the waiting period has gone on too long, raise the alarm with your system administrators. Ask them to examine the logs to see what has happened, and to determine whether the process is still running.

If you have no joy there, start the copy process again.

What is the Copy Space plugin?

The Copy Space plugin is an add-on that you can install into your Confluence wiki. It gives you a way to copy the content of a space to a new space, with a new space key. One of the Confluence developers wrote this plugin for the Atlassian technical writers, and it’s available for everyone else to use too. It is not a supported plugin, but we use it all the time. It would be very difficult to do without it.

There’s a request for the Copy Space plugin to be supported and bundled with Confluence: CONF-14198. If you like, you can vote for and comment on the issue. If the plugin were supported and bundled, we could ask for better handling of long-running tasks. 🙂

Banksia flower

I love the colours of this Banksia flower I saw when walking in the Australian bush. The flower head is made up of hundred of tiny individual flowers. (Ref.) Perhaps 500, or even 504? 😉

Invitation to join me in webinar about Confluence and technical documentation

I’ll be presenting a session at a webinar on Thursday 12 April (in most time zones), hosted by Atlassian. The webinar is titled “Confluence as a platform for technical documentation“. We’re packing three sessions into this webinar, so it should be fun and full of information. The other presenters are Tobias Anstett from K15t Software, and Darryl Duke from Stepstone Technologies. I’d love it if you could join us. It’s free. 🙂

I’m excited about this webinar, because it’s about an aspect of wikis that I’ve come to see as very important: the fact that wikis are extensible, versatile, and built to be so. As a result, there’s a community of enthusiastic developers and innovators who devote a good deal of time to extending wiki functionality, challenging the wiki software owners, and keeping the wiki at the forefront of web technology.

I think that we technical communicators can use this characteristic of wiki technology to great advantage. Technical communicators are in the thick of things. We work in diverse environments, innovate, share ideas, collaborate, and write about the latest technologies and methodologies. We need a tool that can keep up with us.

This webinar focuses on Confluence, the wiki developed and sold by Atlassian.

Webinar details

Title: Confluence as a platform for technical documentation

How to join:  Go to the webinar registration page.

Date and time: The registration page has a neat time zone converter. Here is the time in some time zones:

• US Pacific time: Thursday 12 April 2012 at 8 am
• US Eastern time: Thursday 12 April 2012 at 11 am
• Amsterdam time: Thursday 12 April 2012 at 5 pm
• Sydney time: Friday 13 April 2012 at 1 am (yes, that’s right, 1 am)

Length: 60 minutes

What’s in the webinar

People from two different plugin development companies are joining me to present parts of the webinar: Tobias Anstett from K15t Software, and Darryl Duke from Stepstone Technologies. That’s so exciting!

I’ll kick off, with a discussion of Confluence as an extensible platform.

• The extensibility and versatility of the wiki stood me in good stead recently, when I used Confluence to write and publish a book. I’ll talk about the benefits of writing on the wiki, the plugins that we added to the wiki to provide the functionality we needed to produce the book, and how we worked with the plugin developers to extend the functionality even more.
• Moving to the broader arena of technical documentation, we’ll look at some typical requirements of a documentation tool. I’ll discuss whether core Confluence functionality satisfies those requirements, and point out the plugins that we can add to give us what we need.
• I’ll also show how technical communicators can get involved in the development of wiki technology.

Next up is Tobias. The K15t team develops a number of Confluence plugins specifically for technical documentation. The company’s vision statement  is, “We believe that wiki-based technologies will be the future for documentation.” Yes! Tobias also spent a lot of time with me and Richard Hamilton, of XML Press, extending the Scroll Wiki DocBook Exporter plugin to enable us to produce a book on the wiki. It will be great to share the webinar with Tobias. His part of the session is called, “Complete the Documentation Life Cycle with K15t” and he’ll show us how to use the K15t plugins in the documentation life cycle.

Darryl will conduct the third part of the webinar, titled “Simplify and brand your Documentation with Stepstone’s Zen”. Zen Foundation is a theme that you can add to Confluence. It is available as a plugin, developed by Stepstone Technologies. A theme changes the look and feel of the wiki site, and can add significant functionality too. I’ve recently worked on the Atlassian Developers site, a Confluence site that uses the Zen Foundation theme. Darryl and the Stepstone team were great in helping us to develop the brand we wanted for that site, and in customising the theme for our needs.

Prizes too

There are some prizes to be won! When you register, your name will be entered into a draw to win one of these:

• One of 10 copies of my  new book: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. (Thank you to Atlassian and XML Press for making these available.)
• A Zen Foundation license valued up to $12,000.
• One of K15t’s Scroll Wiki Exporters valued up to $3,600.

Questions and chat

If there’s time at the end of the webinar, we’ll open it up for questions. Come and throw them at us. 🙂