Blog Archives

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.

A report from ASTC (NSW) 2011 day 1 morning

I’m at the 2011 conference of the Australian Society for  Technical Communication (ASTC), New South Wales branch. It’s great to get together with other technical writers, greet old friends and meet new people. It’s also great to talk about the things that matter to us as technical communication professionals. Here are my notes from the morning of day 1.

President’s welcome, by Bede Sunter

Bede Sunter, president of the ASTC, opened the conference by with a concise description of the role of technical communicators: Supplying information of value. He briefly discussed the role of technical communicators and its relationship with the Plain Language movement. After welcoming everyone, he handed over to Pam Peters

Beyond words, by Pam Peters

The key note presentation was by Pam Peters, adjunct professor in linguistics at Macquarie University. Pam has contributed to a number of dictionaries and written style guides such as The Cambridge Guide to Australian English Usage. She introduced herself saying that she was here as a linguist who is increasingly interested in visual communication, and the visual dimensions of language as used for communication purposes.

Pam’s presentation discussed contrastive typography, its decorative uses, and most relevantly  its functional uses as a resource for communication. One example was the use of visuals to clarify architectural terms. These visuals may be as simple as a picture. Or they may be diagrams for showing the relationships between different terms. She showed us a tree structure to represent the classification of windows by their shape. Shape is just one of the ways in which we can describe windows. This was part of the “term bank” that Pam and her team are developing. Another example was a concept map, similar to a mind map or a data relationship diagram, showing the relationships between facets of sustainable architecture.

Pam discussed the benefits of tabular information: It is both wide band (a lot of information) and gives the reader control. The reader can decide what to focus on. She illustrated this with a table that Tufte had created for a criminal trial, showing the types of crimes committed by witnesses in the trial. Evidently this table had a big effect on the outcome of the trial. Other graphs showed the causes of death over a given timeline. Again, the graphs were created by Tufte.

Pam closed by saying that the visual elements are parallel methods of communication to the words and numbers. If you can use these elements meaningfully and strategically, you can become a multimodal communicator. This is the way everyone wants to go.

Keeping your customer happy – it takes more than words, by Elizabeth Abbott

Elizabeth Abbott is director of TechWriter Placement and Services. She mentioned that she gets lots and lots of feedback about the way her company’s contractors interact with clients. She stressed that this is a very important part of our job, for people who have permanent roles as well as contractors. The focus of Elizabeth’s talk was on understanding non-verbal cues: Listening to the customers, giving and receiving feedback, and body language. A good question to ask yourself, when dealing with a customer, is: “What can I do to make this person successful?”

Elizabeth’s talk was very informative, and given by someone who obviously has a lot of experience in this field and has thought about it and formulated her guidelines with skill and care.

A bit of everything – multiple platforms with minimal editing, by David Whitbread

Author of The Design Manual, David Whitbread presented a session on “a bit of everything”. This is something that most of us are doing these days. A big concern is versioning. By that, David means which version of the information are we delivering. How can we come up with one definitive version, or one definitive document, and then feed it out to the various media? This was the subtext of David’s talk, including metadata tagging and visual media.

David started with the capture and curation of content. Curation is a new term, but it is really what authors have always done. He talked about using podcasts as a way of quickly capturing information from subject matter experts. Within ten minutes, he has a good chunk of content. The lawyers with whom he’s been using this technique are very happy with this process, because it’s much faster than text capture and it gives the lawyers control over the content. Transcripts then provide the textual element. A similar process is used to reuse the presentations given by the lawyers at conferences.

Navigation and labelling are essential for helping people fin dthe information they need. Headings must signpost the information. Semantic tagging is useful for gathering related information and pushing it out in a different way. For example, you could label all headings as heading1, heading2 etc. You could also label all quotations as such. This is the metadata that is useful for sending out summaries, or content targeted at specific audiences, and so on.

David says that design is going to get easier, because now we’re designing the pieces of the document. How they will finally appear is determined by a number of factors, including the users’ choices, the output medium, the browser, the device, and more. Technology plays a big part in how design will become simpler. See the example of The Guardian mobile app. The source  files for the Guardian pages are scanned by the software, and it works out how to display the article for the app. The designers just go in and add the final touches. David recommends that we look at the reviews of The Guardian app, in CreativeReview and other locations. (Here is one that I found:

We want our messages to gracefully reflow to suit the technology of the user. The Guardian app is a great example of this.

David’s talk also skimmed over findability and accessibility, branding and marketing, websites and social media, and film and sound.

Workshops to webinars – the future of training for technical communicators? By Steve Moss

Steve Moss is president of the Technical Communicators Association, New Zealand (TCANZ). His session covered the strengths and weaknesses of webinars and workshops as training tools. The notes that Steve gave us in the conference workbook are very comprehensive indeed, and will be very useful for anyone intending to run such a training session. TCANZ has run over 60 workshops and webinars over the last few years. The presentation contained the tips and techniques that Steve and his team have learned about the process of organising and running workshops and webinars, with a focus on webinars. They have run five webinars since 2010, including sessions with presenters in the UK, US and New Zealand.

This was a very informative talk, covering all you need to know about planning and holding a webinar or workshop.

Off to lunch

It’s lunch time. More news from ASTC (NSW) 2011 in my next post.

Social web documentation strategies – notes from Anne Gentle’s webinar

Early, very early, this morning I attended a webinar run by TCANZ, with Anne Gentle as the guest speaker. The webinar was titled “Social Web Documentation Strategies” and was based on Anne’s STC Summit 2010 presentation. I really enjoyed hearing Anne speak in person! Here are the notes I took from the session. Any mistakes are mine, and all the credit goes to Anne. 🙂

Anne started off discussing the fact that it can be risky to introduce social strategies into your organisation. To help reduce the risks, she suggests these 3 steps:

  1. Listen first. See what’s out there and get the feel of the existing communities.
  2. Find your role. In the presentation, Anne discussed a number of the roles applicable to documentation on the social web.
  3. Align your content strategies with business goals. Everyone brings certain expectations to websites, and they bring different levels of expectation to different types of content.


Anne points out that technical writers are very good at this. We are technically skilled and we know a lot about our products. She suggested some tools:

  • Google Alerts. You can do really precise searches. For example, you can search only blogs, and pick up content about only your product. You could view your entire customer database as a community, and get insight into the things they are talking about. Anne works on a project called OpenStack, with Rackspace. She finds that bloggers are a very good community to start a conversation with.
  • Technorati offers a blog-only search. This is neat because it includes a filter based on authority, taking into account how often the content is linked to, how many influential people link to it, and so on.
  • Delicious and tagging. If you know who in your community may be tagging, this is a good way of finding out who is talking about what.

This is all part of the listening phase. Don’t jump in and start talking too soon. Don’t automate your tweets or posts. Don’t automatically follow people. Do identify yourself and the company you work for. At Rackspace, where Anne works, the social media policy is “be helpful when you are online”. Anne also recommends that we should be conversational: let it flow and be natural.

Anne talked about checking the “social weather”. She compared it to checking out the atmosphere in a restaurant. Is it quiet and romantic, or crowded and noisy? In the same way, online communities have different atmospheres and conventions.

Another useful technique is “sentiment ratings”. You can do them in Twitter Search (advanced search) . More heavy-weight tools are Radian6 and others. This technique gives you an idea of whether customers are happy with a tool, or more likely to hate it. Radian6 was recently acquired by SalesForce. The tools are becoming more advanced. See what clues there are on the social web to get a good picture of what our customers feel about our product.

Social technographics is the art of finding out how likely people are to take part in social web activities. Are they like to write a blog, tag something in Delicious, post tweets, and so on? The tools analyse the demographics and help you decide whether people in your target audience are likely to actively create content or take part in your activity, or are more likely just to read. This helps you to choose the social activities you want to initiate.

At this point I lost my Internet connection and was offline for ten minutes or so. When I got back online, Anne had moved on to talking about roles.

Finding your role

Anne is now talking about roles, I may have missed a few due to being offline. This is where I came back in:

  • Reporter/observer role. This is someone who has good listening skills, and spends time finding out who is writing the really good stuff.
  • Enabler role. A good tool is DISQUS, that provides a widget at the bottom of each page where people can comment. You can see threaded conversations, moderate the comments, even migrate comments from one page to another. The role of enabler is one that Anne fulfills. She gave an example of seeing a comment about a particular tool on the documentation, and how she was able to connect the customer with the developer of the tool.
  • Sharing role. Provide tools on your site that people can use to share your pages via Twitter, Facebook, and so on. For example, a tool called TweetMeme adds a retweet button to a page.
  • Syndicating your content, so that people can subscribe to it. You can offer people notifications about updates to content, and you can embed content from RSS feeds onto your own pages. Anne showed us an example of a side panel she has added to a page, showing a feed from a particular blogger who was writing content relevant to her documentation.
  • Collaborator/instigator role, telling people what content needs writing. This works really well in an agile development environment, where you are actively asking people to write the content. You need a content platform where everyone can edit the documentation. In the open source development environment, collaboration is actually a technical requirement. If this makes sense in your business, you would go to the “final frontier” and provide this type of community documentation. You need to align this with your business goals.

Aligning your content strategy with business goals

Anne gave a list of business goals that align themselves really well with a social documentation strategy.

  • The need to track a campaign or the effectiveness of your content.
  • Creating customer experience of collaboration and community.
  • Helping people to help each other: peer to peer support.
  • Decreasing the response times on support requests.
  • Generating ideas. People in a community bring lots of ideas. If they are willing to share and contribute these ideas, you can crowd-source ideas.
  • Rewarding contributors by offering them special experiences. Even rewards that are not monetary are valued, such as badges and other types of recognition.

The way we do business is evolving. We want these social customer insights. No matter where you are in the business, whether in marketing or other areas, there are use cases for using social tools and the social web for meeting these goals. Social CRM is gaining traction. The famous use case is Heather Armstrong who runs a blog called One day her dryer broke when her baby was only a few days old. She couldn’t get it fixed. Repair men came and went, but nothing worked. So she started tweeting about it. That’s exactly what the dryer manufacturer does not want. They want her to tweet rather about how positive the relationship was. Anne says that the onus is on the business to meet the customers where they are.

Starting your own community

Before jumping, you need to realise that there are communities out there already. For example, forums, Twitter chats, a popular blog. Before building your own community, find out if there is actually one already that you can collaborate with.

For example, the Mozilla Developer Network is becoming a bit of a hub about Google Chrome too. Anne thinks this is really great. They could have started their own community. Instead, they joined an existing one.

Pitfalls. Anne mentioned a number. Here are just a few.

  • Too much content, without enough opportunity to take part and become engaged.
  • High barriers to entry.
  • Should you run a pilot, a sort of trial with a limited audience? One problem is that people may not believe that you are fully committed if you do a pilot. You need to analyse your community. In some cases, a pilot may indeed be helpful.

Next Anne ran through the benefits of measuring the participation and engagement in your community. You need to set up some KPIs. These are a few of the measurement points that Anne mentioned:

  • New versus returning visitors. Do you want a high number of new visitors, or is it more important that people keep coming back?
  • Time on site: You may want people to spend a lot of time, or maybe the fact that they found the answer and left is good.
  • Search results. Did people find what they were looking for?
  • Download rates. Did people find and download the content they needed?
  • Do people add comments, and are your support staff answering them?

After doing all this analysis, then you can make the decision about whether it makes sense for your business, to apply a social media strategy.

Then you launch and learn.

At this point Anne called out to me and said that I’ve been an inspiration to her. Wow, thank you Anne. The same is so true in reverse.

Managing community content

Next Anne gave a number of pointers about managing community content. For example, you must be able to accept content that is not 100% perfect. You need to help people build a relationship with content. They’re not likely to build a relationship with text only. A good tip is to add a profile picture of yourself.

Anne showed the example of Adobe Community Help. It is all searchable, including the comments and user-generated content. Anne was looking for some information, and found the answer in a comment from a technical writer who said she couldn’t put it in the official documentation because it was more in the way of a workaround for the way the product worked. This is a great way of getting help.

Anne ran through a couple more examples: Intuit, Mozilla, Ubuntu and OpenStack. The OpenStack project is where Anne works, and she talked with enthusiasm about the great experience she and the team are having in building the social site.

An interesting analysis showed that there are four motivations for people to contribute:

  • I help someone because they will help me.
  • I want to build my reputation.
  • I feel obligated to help, because it’s a great tool that is helping me.
  • I feel like a I belong, because it’s a fun community.

Summing it up

In closing, Anne went back to the point of aligning content with business goals. Which areas of the business are we aiming to support? For example, marketing and sales, service and support, research and development, and so on.

She said that we need to do this. Yes, it’s scary and confusing. But there is a target and there is a goal: Serving customers with our content.

My conclusion

Thank you so much to Anne Gentle and to TCANZ for hosting this webinar. Anne is a great speaker. Her enthusiasm and professionalism both shine through. For me, it was definitely worthwhile being online at 7am!

Black swans

Black swans in autumn

TCANZ 2010 wrapup

This week I attended the TCANZ Conference 2010 in Wellington, New Zealand. I’ve already written some posts about most of the sessions I attended. This post is a wrapup, with links to those posts and some general information about the conference.

First of all, a very big thank you and warm congratulations to the conference organisers. This was my first time at a TCANZ conference, and I loved the people, the information-rich sessions and the venue. It struck me again and again how much care the organisers took of the speakers and of the delegates. As a speaker myself, it was wonderful to be invited so charmingly and to be welcomed into New Zealand so heartily. Thank you Emily, Margery, Steve, Roy, Luke, Emma, MaryAnne, Sarah and everyone else involved in creating such a great event. And thank you to Emma too for the scintillating, tantalising introductions to each speaker!

The sessions

There were about 60 delegates at the conference, and 14 sessions spread over 2 days. Nine of the sessions were presentations by invited speakers, on the topic of intranet solutions. There were also the introductory session, three product presentations and the speaker forum.

I’ve written posts about most of the sessions I attended. There were a few where I just sat back and listened rather than taking notes. Here are links to my summary posts:

New friends, chit-chat and learning

It’s all about meeting people. Along the way, I learned a lot and had a lot of fun.

Here are some pictures of the conference dinner on Thursday night. The food was excellent and the company was outstanding!

(Click the images to see a larger picture.)

TCANZ 2010 wrapup

TCANZ 2010

TCANZ 2010 wrapup

TCANZ 2010

TCANZ 2010 wrapup

TCANZ 2010

The speaker forum

The very last session was the speaker forum. It was a fun, raucous, thought-provoking and above all terrifying end to the conference. 😉

MaryAnne picked 6 speakers as her victims. I was lucky enough to be one of them. She then took some scraps of paper, wrote the beginnings of some sentences on them, and put them into a cup. Each of us had to draw a scrap of paper from the cup, read the words on the paper and continue speaking. Instantly, with no preparation, and for about five minutes!

The phrase I drew was:

If technical communicators ruled the world, I would take on…

Imagine how you’d continue speaking on that topic, in front of an audience of 60!

Actually, we all acquitted ourselves fairly well. The audience chipped in, lively debates arose, and chickens somehow featured prominently. Well done, MaryAnne, it was fun and a great way to close the conference.


Heh, I’ve learned at last how to pronounce “TCANZ”. It’s “T-Canz”, not “T-C-A-N-Z”. Seriously though, this is a conference well worth attending.

TCANZ 2010 day 2 – Confluence wiki as an intranet

This week I attended the TCANZ Conference 2010 in Wellington, New Zealand. I’ve already written a few posts about the other presentations at the conference. Now it’s the turn of my own session, called “Let’s take a wiki for a spin”. It was all about Confluence wiki as an intranet platform.

I gave a hands-on demo of Confluence wiki, focusing on the features that are great for its use as an intranet. Sprinkled here and there are some tips on how we use Confluence as our own intranet at Atlassian, and some ideas on how to get employees enthusiastic about using the intranet and how to ensure they feel a sense of ownership of the intranet.

Downloading the presentation

If you like, you can download a copy of the slides in PDF form. They may be useful, even though the presentation was a hands-on demo. I’ve put a lot of information and references into the speaker’s notes too.

A summary of what’s in it

The presentation covers these areas of using Confluence wiki as an intranet:

  • Introduction to Confluence wiki.
  • Creating a space. In the session, we created the technical communication space, where members of the tech comms team can share their procedures, news and other information. We customised the space home page and looked at various ways of structuring the content of the space.
  • Customising the dashboard. We looked at the default dashboard and tried out two ways of customising it. We talked about the advantages of letting all employees change the welcome message on the dashboard and contribute in other ways to the content, keeping it fresh and interesting.
  • Publishing a blog post. We wrote a blog post and used the gallery macro to produce a pretty display of pictures. We discussed the idea of making new starters write a blog post on their very first day, and how well that works to get them using the intranet and to introduce them to the company.
  • Helping other teams with their spaces. We looked at some of the more technical aspects of content creation, and how technical communicators can help the organisation get the most out of its intranet wiki.
  • Staying on top of the news. How can you keep up with what’s happening in the organisation and yet avoid being swamped by the news? We looked at RSS feeds: What they are, how to build them and how to read them. Then we examined the email notifications that the wiki can send, and how you can tailor it to send just what you want to know: Watching a space, watching a page, following people and setting your notification options.
  • Taking your own wiki for a spin. It’s surprisingly easy to download and install a wiki and run it on your laptop or desktop PC, just as I was doing for the presentation. The slides contain some pointers to getting hold of Confluence. Other wikis are fairly easy to try out too.
Let me know if you download the slides and what you think of them.
%d bloggers like this: