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

A technical writer in Sydney – and some trees

Julie Norris had a great idea this week. She has created a YouTube channel specifically for the #tcchat Twitter chat group, and she’s uploaded a video of herself and her corner of the world. Now she’s inviting us to do the same. What a lovely idea, thanks Julie!

So I’ve spent the last few days making a video and uploading it to YouTube. To cut a long story short, here’s the video. As Julie suggested, the video introduces me as a technical writer working in Sydney, and shows you a bit about my surroundings:

I think it’s a cool idea that will help to bring far-flung technical writers closer together, especially those of us who take part in the #tcchat Twitter chat group.

The long story

It took many, many tries to get this far. I have to confess that the air turned a delicate blue hue at times. Why oh why are movie formats so finicky, fussy and frustrating? 😉

I first read Julie’s post when I was on the bus on the way to work. Unsurprisingly, I did not have my camera with me. I did, however, have my sparkling new iPhone 4, which does movies. Cool. I made a cute movie of the Sydney Harbour Bridge through the bus window, and of the building where I work. On the way home, I filmed a Paperbark tree flapping in the breeze and a Sydney Red Gum glowing in the gentle afternoon light.

The next day I sallied forth with my “real” camera and took some more movies.

Then I attempted to splice them together. Disaster. I tried free software and trial versions of expensive software. Suffice it to say: Nothing works perfectly.

So in the end, I’ve decided to use the software that came with my Canon camera. It’s pretty good, but it is not able to merge the movie files made by the iPhone. It gets the picture OK, but no sound.

Oh, and I’m fond of Australian trees. You’ve probably noticed there are a couple in the movie above. 🙂

A smooth ride through the text

Part of our job as technical writers is to give our readers a smooth ride through the text. And it’s not a small part of the job either. It’s important, even if it means we spend a fair bit of time correcting other people’s writing. Or does that just turn us into glorified copy editors — what do you think?

This isn’t new to most tech writers, but it came to mind again recently when I was making a couple of very small corrections to a page in our Confluence documentation. A reader had added a comment to the page, saying that she had noticed a couple of typos. Thank you Rosie 🙂 (The comment is still on the page at time of writing this blog post, but it will probably disappear in a couple of weeks.)

Rosie had picked up two spelling mistakes: “serch” and “mutliple”. I myself find the second one particularly bothersome, because my eyes don’t quite believe that they’re seeing it right. So they go back a couple of times just to check that the mistake really is a mistake.

Why is this important?

Because we don’t want to distract our readers from the important stuff just because it’s written funny 😉

OK, so prove it!

It’s easy enough when we’re talking about simple spelling mistakes. “Serch” should obviously be “search”. And “mutliple” is just painful. But what about the more complex aspects of grammar, vocabulary and style?

When you read a sentence like this:

Sarah is eat a chocolate.

you’re hit by a LAN.

And this one:

On the way to work this morning I saw a goldfish swimming around the bus.

gives you an N400 when you read the word “bus”.

A “LAN” (Left Anterior Negativity) is a measurable blip in the electrical impulse which your brain emits when your internal language processor encounters something ungrammatical — like the word “eat” in the first sentence. The blip takes between three and seven tenths of a second to register on an EEG.

An “N400” blip happens when you encounter a word which doesn’t fit the context – like the word “bus” above. This one takes about four tenths of a second.

This information comes from Steven Pinker’s book, Words and Rules. It was pretty cool to learn that there’s a measurable physical manifestation of that feeling of discomfort I get when a sentence jars.

But what is “correct” English anyway?

I might suffer a LAN zap when you write “Remember to invite Peter and I to your party”. But many people don’t!

(BTW, “Peter and I” is wrong in that sentence, and I’m ready to battle that one out to the end if anyone’s game to take me on 😉 )

Or you might get a LAN buzz when I start a sentence with the word “or”. But I think it’s OK.

Why does the tech writer get to decide what’s right and what’s not?

We don’t. Language is a living, changing thing. Different words and constructs will sound good or bad to different people and at different times in history. Consistency is the key. Provided a document or a documentation suite is consistent in its usage of grammar, style and vocabulary, the reader will get that fabled smooth ride.

So which standards do we use? It doesn’t matter all that much, provided you pick a standard that is recognised in your neck of the woods.

At Atlassian, where I work, we use these two guides:

  • Style manual for authors, editors and printers (John Wiley & Sons Australia)
  • Macquarie Dictionary, Fourth Edition of the Essential Dictionary (University of Sydney)

We’re based in Australia. Our US office has copies of these books too, and we’ve agreed to go with the Australian standard because we’re originally an Ozzie company. I suspect that many Americans think it’s cute 🙂

Taking standardisation even further…

Scott from DMN writes about a DocTrain West session he attended, given by Berry Braster and listing the advantages of Simplified Technical English.

A Scribbly Gum tree in my garden

Moving on to scribbles and smoothness of another sort… The Scribbly Gum tree is quite common in this part of Australia. It has a lovely smooth white bark which gleams silver in the wet.

A smooth ride through the text

A smooth ride through the text

As you get closer, you notice some weird zigzag lines marring the smooth surface. It’s just as if someone has scribbled on the bark.

A smooth ride through the text

A smooth ride through the text

The markings can be quite intricate and almost seem have some meaning which you can’t quite discern.

A smooth ride through the text

A smooth ride through the text

But actually, the “drawings” are tunnels dug by the larvae of the Scribbly Bark moth, known less intimately as Ogmograptis scribula.

A smooth ride through the text

A smooth ride through the text

I vote that we make the Scribbly Gum the mascot of technical writers. All in favour say “aye” 🙂

%d bloggers like this: