Blog Archives

Introduction to API tech writing – upcoming webinar

On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.

The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!

APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.

Details of the webinar

Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.

The session covers the following topics:

  • What an API is and does.
  • Introduction to the role of API technical writer and our audience.
  • Overview of the types of developer products we may be asked to document – APIs and others.
  • Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more.
  • A couple of live demos of APIs that you can play with at home: a JavaScript API and a REST API.
  • Examples of good API documentation.
  • The components of API documentation, and the technical writer’s role in the creation of each component.
  • A day in the life of an API technical writer.
  • Tips on getting started in the role.

Here’s a link to the slides on SlideShare: API Technical Writing.

Introduction to API technical writing

More in the STC’s webinar series on API technical writing

Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.

I hope to “see” you at the webinar!

Invitation to webinar – Wiki: what works and what hurts

TCANZ, the Technical Communicators Association of New Zealand, will host a webinar on 25th/26th of June, at which I’ll present a session called “Wiki-based documentation: What works and what hurts“. I’d love it if you could join us.

The webinar is a live, online presentation. We’ll see social and collaborative documentation in action, on the Atlassian documentation wiki.

What’s the aim of this webinar?

I’ll show you what’s great about technical communication on a wiki.

But you’ve probably heard a lot about that already, from me and other wiki technical writers. So I’d also like to talk about the aspects of wiki-based documentation that are more tricky, and share some hints about what our technical writing team is doing about those areas.

The TCANZ webinar page has more details about the content of the session.

Date, time and registration

If you’re in the Asia-Pacific region like me, you’ll be delighted to know that this webinar happens at a civilised time of day for us. 🙂

Date: Tuesday 26th June 2012 (which is Monday 25th June in some parts of the world)

Time: 11:00 a.m. on Tuesday 26th June in New Zealand
9:00 a.m. on Tuesday 26th June in Sydney
4 p.m. on Monday 26th June in California
7 p.m. on Monday 26th June in New York

You can use the WorldTimeServer to see the time in your own time zone.

Fee and registration: See the TCANZ webinar page.

Recording of webinar about Confluence wiki, collaboration and technical communication

Yesterday I presented a Scriptorium webcast titled “Collaboration: A hands-on demo using Confluence wiki“. The kind folks at Scriptorium have made a recording of the webinar available, and I’ve uploaded my slides too.

This presentation is about collaboration and what it means to technical communicators, and how we can use a wiki to enhance the experience. I give a hands-on demonstration of creating a technical documentation space on a wiki. You will see how to design a home page using the Confluence editor, macros, and even a touch of Twitter integration. You’ll also see how to draft a page, invite subject matter experts to review the page, and keep track of what they do to your documentation. After walking through the simple workflow of draft, review and publication, I discuss the use of add-ons and plugins to supply more sophisticated workflow functionality.

It was great to get some questions from attendees and answer them at the end of the session too. Having a live wiki up and running was very useful to illustrate the answers!

Webinar recording

Scriptorium has published the recording of the webinar on SlideShare: Webinar: Collaboration: A hands-on demo using Confluence wiki

Slides with speaker’s notes

Once you’ve watched the webinar, you may find it useful to see the slides with my speaker’s notes. The slide deck includes screenshots of the parts of the demo that were live on the wiki during the presentation. The slides available on SlideShare: Slides: Collaboration: A hands-on demo using Confluence wiki.

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

Who is Donna Dark?

Donna is a denizen of my demo wiki. She’s a technical communicator extraordinaire. Take a peak at the webinar recording. You’re bound to bump into her.

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

%d bloggers like this: