Blog Archives

Invitation to a webinar about collaboration on Confluence wiki

I’m presenting a session in a Scriptorium webinar about collaboration and technical documentation. The webinar is on Thursday 26 April 2012. (Actually, the date depends on your time zone. It’s Friday 27th April in Sydney.) The session is called “Collaboration: A hands-on demo using Confluence wiki“. Can you join Sarah O’Keefe and me? We’d love to have you there. :)

Part of the session is a hands-on demo, because I want to show you what it’s like to work on a wiki. The hands-on sections are interspersed with slides, so that we can discuss concepts and ideas too.

The webinar is free of charge. What’s more, you have a chance to win a copy of my book, Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication.

Webinar details

Title: Collaboration: A hands-on demo using Confluence wiki.

Date and time:

  • Thursday, April 26th at 4:30 p.m. US Eastern time.
  • Thursday, April 26th at 1:30 p.m. in California.
  • Friday 27 April at 6:30 a.m. in Sydney, Australia.
  • Find the date and time in your part of the world. You can use the meeting planner at the World Time Server to compare times in different places. For example, here’s a link that compares the times in New York, California, Sydney and London.

Registration: Go to the Scriptorium webcast page.

Another Scribbly Gum tree

I’ve posted a few pictures of Scribbly Gums on this blog. They’re fascinating and beautiful. The name of the tree is similar to the name “Scriptorium”, which gives me some excuse for putting this picture here. And this time, unlike in my previous post about scary webinars, there’s no spider on the tree. :)

Scribbles made by larvae on a Scribbly Gum tree

The role of webinars in technical communication

Last week I was co-presenter in a webinar. It was an interesting, invigorating and fun-filled experience. There was even enough of a dose of terror to give a pleasant buzz afterwards. :) Since then, I’ve been musing about the role of webinars in technical communication. I’d love to know what you think, and hear any stories of your own webinar experiences. Are webinars a good tool for technical communication? Can we and should we be thinking about doing more of them?

The details of the webinar itself are in two earlier posts: the invitation and the report, which includes a link to the recording.

The plus points about webinars as tech comm tools

We can gain new insight into the product that we’re documenting. When putting together the material for the webinar, I realised it was a great opportunity for me to think of the product in a different way. I didn’t want to repeat the material that’s in our documentation. Instead, I took a look at the product as it’s seen by a large group of customers and by the developers who build the product and its add-ons: a wiki as extensible platform.

A new slant in the user assistance for a product is valuable to the audience too. It gives them another way of taking advantage of the product and of the community of people that provide services around the product. By coming at a product from a different direction, people gain a broader understanding of it and will be able to make deductive leaps when using the product for their own requirements.

One attendee tweeted:

“it’s a bit embarrassing to learn so much in 1 hour after 8 years of using [the product]“.

Thanks for that tweet! It was very rewarding to hear. And I don’t think it should be embarrassing. Instead, it proves the point that a new angle can work wonders.

There’s a strong aspect of marketing in a webinar. You’re representing your company and the product. A webinar provides a focal point for buzz generation. Tweets and blog posts flock around the webinar, both in the leadup and in the report and analysis afterwards. This marketing aspect ties in well with recent discussions in the technical communication world, about our changing role. Maybe webinars are a good way of adding value to our organisations, over and above the day-to-day tasks of a technical writer?

In preparing for this webinar, I collaborated with our marketing team. They converted my slides to the corporate template. I’d thought my own slides were pretty cool, but Terrence Caldwell (product marketing manager) added a distinctive touch of class. Thanks Terrence! The marketing team also handled all all the organisation of and hosting of the webinar. Our technical writing team often collaborates with the marketing team on special projects and documents. It’s great to learn from them – a mutually enriching experience.

Another plus point was working with co-presenters on the webinar. As the first speaker, I made sure that my presentation introduced the other two speakers, and included some material that would act as a lead-in to their sessions. I loved sharing the responsibility with them, knowing that their different viewpoints would make the webinar a good learning experience for the attendees. I have learned a lot from their presentations too.

Interaction with customers and other interested people is another good result of a webinar. During the session, people asked questions by typing them into the online chat. I was kept very busy answering them! Afterwards, many people have tweeted comments, sent email messages, and added comments to blog posts.

Finally, preparing for and presenting the webinar was invigorating and fun. It’s given me new ideas and new energy. I recommend it to anyone who’s brave enough to sit in a room and talk to the ether without knowing what the ether is thinking. ;)

The cons

Preparing for a webinar is time consuming, and it’s hard work. We need to weigh up the effort involved and the resulting benefits to the company. Our marketing team is enthusiastic about webinars as a way of engaging customers. They also see the value of having a subject matter expert give the presentations. We sometimes invite external speakers, in so-called “voice of the customer” webinars. From that point of view, it makes sense for a technical writer to present a session about using a wiki for technical documentation.

The technology is good, but things can go wrong. For our webinar, we had one presenter in Australia (that’s me), one in Europe, and one with the webinar hosts in the United States. The person in Europe had problems with his Internet connection, and we had to delay his presentation while he searched for a better line. Luckily, we could just shuffle the order of two of the presentations, and it all worked well in the end.

Time zones can be a problem. For me, the webinar started at 1 a.m. Yes, the dead zone! I was happy to be awake at that time, but of course not many other Australians were able to attend the live webinar. Instead, we recorded the session and it’s now available online.

Presenting a webinar is scary. But that’s part of the fun. :)

So, what’s it like to present a webinar?

Kai Weber wrote a great post recently: So what’s it like to present a tech comm webinar? I’ll just add a bit here too (repeated from my earlier post announcing the webinar recording).

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!

Something almost as scary as presenting a webinar

This photograph is quintessential Australia. It shows a spider on a web attached to a Scribbly Gum tree. I snapped it while out walking in the bush this morning.

Spider on web on Scribbly Gum tree

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

A quick update on my book

The Confluence, Tech Comm, Chocolate wiki is buzzing! That’s where I’m writing the book, and that’s where the technical reviewers are giving their feedback at the moment: on the wiki. It’s good fun seeing all their comments flow in. Their input is very useful indeed.

My earlier post let everyone know that I’m writing a book about technical communication on Confluence, titled Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. We’ve been busy with the technical review for the last two weeks. The review phase finishes this weekend. Then I’ll incorporate all the feedback, finalise the content and compile the index. The deadline for final content is end of December. I’ve taken two weeks’ leave, starting today, to focus on the book and meet that deadline. Yaayyy!

I submitted the book proposal in May 2011. Publication is due at the end of January 2012 – a little over a month away. I’ve been keeping track of the time spent on various aspects of the project: writing, admin, design, review, and promotion. When the book is out, it will be interesting to see the proportion of time spent on each activity. I’ll publish some graphs and a timeline. There are probably one or two technical writers out there who’ll be interested.

Hehe, that makes me think of what our CEO said when he heard that I’m writing a book. It was something like this: “Congratulations! All technical writers are frustrated authors, aren’t they!” He said it with a big smile. :)

A quick update on my Paperbark tree

Just over four years ago, at around the time when I started this blog, I also planted a couple of trees. One of them was a Prickly Paperbark. A few weeks ago it flowered for the very first time. The timing is rather nice, because the flowers bloomed just as I posted the announcement of the book!

Here’s a closeup of the flowers:

New guide to developing technical documentation on a wiki

We’ve just published a new set of documents in our wiki’s user guide: Developing Technical Documentation on Confluence Wiki. We started writing the guide during our recent doc sprint. Since then, I’ve put it through a technical review and added some bits. Now it’s part of the “official” documentation. That’s a doc sprint win. :)

Designing and developing this suite of documents was a lot of fun and very interesting. The project serendipitously combined a number of aims, all rather different in nature:

  • Think up something to do in the doc sprint.
  • Involve other doc sprinters in the project, especially people from outside the company.
  • Spike a “use-case focused” guide and make sure the result is useful even though it’s a spike.
  • Tie together all the information we have in various spots, about writing technical documentation in a wiki.
  • Put the guide into the core Confluence documentation, so that it will be maintained and updated from now onwards.

People who worked on the guide during the doc sprint

A number of people collaborated on this guide. Two were Atlassians and the rest were people who joined the doc sprint in November:

…and others who reviewed the pages, working remotely in various spots around the world.

What is a “use-case focused” guide?

One of the things we’d like to do is to provide more “use-case focused” documentation. By that we mean that the guides should focus on a specific use of the product. A better term might be “domain-focused” documentation. For example, for Confluence we should write documentation about how to use Confluence as an intranet, how to use Confluence as a knowledge base, how to use Confluence for technical documentation, and so on.

This suite of documents is the first stab at such a user guide.

Design of the guide

These are the principles on which the guide is based. It’s just a spike, so we didn’t hit all these goals. But it’s a very good start.

Write topics that are task-focused on the macro level. The words “on the macro level” are very important in this context. It’s a well-known principle of technical documentation that guides should be task-focused, as opposed to feature-focused. We tell users how to do the things they need to do, rather than documenting the features of the product. At the moment, much of our documentation is nicely task-focused on the micro level: How to add a space, add a page, add a comment, set page restrictions, and so on. But it’s not task-focused on the macro level: How to set up a space for technical documentation; how to push a document through the draft/review/publish workflow (using page restrictions); and so on. One good way of addressing this problem is to produce use-case focused (or domain-focused) guides.

Tell people only what they need to know. Focus on the aspects of Confluence that the target users (technical writers, in this case) need. Ignore the other aspects. For example, on a typical technical documentation wiki it’s not important to know how to follow users or use the other “networking” features of the wiki.

Employ progressive elaboration. Progressively reduce the level of detail in the step-by-step instructions, while increasing the complexity of the concepts. Start with fairly detailed instructions for the basic functionality, in the first section of the guide. Become less detailed in later pages, because the users will have become more familiar with Confluence. At the same time, they will be dealing with more complex topics. But that’s OK, because they’re in their field of expertise (domain).

Encourage users to explore the product and learn from the UI, rather than telling them exactly how to do every single thing. If a user guide is very comprehensive, it gives the impression that it documents the entire product. If something isn’t in the docs, people will think it’s not in the product either. They won’t try to explore the product. We should encourage people to trust the UI. Also, if a user guide is very dense, people won’t find what they need in it.

Employ content re-use. Use Confluence’s {include} macro to pull in content from existing pages, so that we can avoid duplicating content and can thus reduce maintenance.

The result

I’m delighted with the resulting guide: Developing Technical Documentation on Confluence Wiki. It’s not perfect, but it’s a very usable and useful piece of documentation and it certainly fills a gap. Thank you again to all those who took part in developing this guide, and to everyone who took part in the doc sprint!

Sydney Red Gum tree

A magnificent Sydney Red Gum tree I encountered on my walk this morning. Shot taken from a rocky ledge half way up the height of the tree.

Follow

Get every new post delivered to your Inbox.

Join 1,391 other followers

%d bloggers like this: