What Homer knew about technical writing

With possible titles of “why consistency works”, or “what Homer knew about technical writing”, or even “what Homer, technical communication and Eminem have in common”, this post is just a musing. And perhaps amusing, in a gentle way. If it provokes any thoughts or ideas in your head, I’d love to hear them!

Homer and other epic poets use a number of repeated phrases. Famous ones are:

• wine-dark sea
• the wily Odysseus
• rosy-fingered dawn
• gray-eyed Athene
• D’oh!
• I’ma make a new plan*

* We could argue that rappers use them too. I suspect there’s a whole blog post right there!

People call these repetitions “stock phrases” and “epic formulae”. People say the use of such phrases is a trick to make it easier to fill a gap in a line of poetry, to keep to the metre when you’re thinking on your feet.

I think there’s a less prosaic purpose too.

In a single familiar phrase, a writer can call up all the connotations and associations that the reader has accrued over the years of exposure to a shared culture. With just two or three words, you can evoke a flare of imagination, a memory, a delightful frisson of fear or just some previously-learned facts.

Ah, the power! Being able to make your reader remember something complex in such a simple way. Efficient, concise, unobtrusive, pleasurable and rewarding.

We do the same with consistency of terminology in technical writing. Ba da boom.

Off topic: I’m fond of trees. I took this picture when walking in the bush this morning.

What Homer knew about technical writing

Twitter Chat for technical writers

I’m so excited about the new weekly Twitter Chats for technical writers, announced last week by Julie Norris and Tristan Bishop! I’ve decided to blog about this great idea, just in case you haven’t seen Julie’s and Tristan’s blog posts and tweets.

Maybe, like me, you’re in the Asia Pacific region and you think,

Oh well, there’s another cool thing I’ll miss out on unless I get up at 3am

But there’s no need to miss out this time! Julie and Tristan have decided to hold two separate chats every week, to have a better chance of suiting all our time zones. That’s so cool! I’m definitely up for the chat that happens at 12 noon on Fridays, Sydney time (GMT+10).

Twitter chat details

Essentials:

• Two sessions weekly. I’m attending the one at 12 noon on Fridays, Sydney time (GMT+10).
• Tag: #TCchat
  

The details are in Julie’s and Tristan’s blog posts:

• Tech Comm Twitter Chat Launches! by Julie Norris
• We Need to Talk by Tristan Bishop

Julie has also written a great post to get us started: Twitter Chats 101.

Thank you guys, what a great idea!

A bush in my garden

Spring has arrived, and wow just look at this bush that we planted two years ago! It’s flourishing in soil about two inches deep, on top of a sandstone ledge. It’s a Leptospermum Polygalifolium Cardwell, also called a Cardwell Tea Tree and is native to Australia (NSW and QLD).

Twitter Chat for technical writers

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:

• Conference introduction and welcome, by Lynda Harris
• Metadata: Key to a successful intranet, by Ann Rockley
• Building a great intranet, by Rachael Fogarty
• Presentation of Adobe Corporation products, by Ankur Jain
• Simple design choices for maximum usability, by Patrick Hofmann
• Author-it Corporation presentation, by Matt Armstrong
• Tools for collaboration, management, and delivery of information, by Rowdy Bristol
• Intranet publishing with Drupal, by Chris Daish and Matthew Hunt
• Confluence wiki as an intranet, by Sarah Maddox (this was my presentation)
• Video killed the redundant writer, by Grant Mackenzie

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

TCANZ 2010

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.

Finally

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.

• Download the slides in PDF form (1,791 KB): Let’s take a wiki for a spin (slides only)
• Download the slides with notes in PDF form (7,304 KB): Let’s take a wiki for a spin (slides with notes)

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.

TCANZ 2010 day 2 – Video killed the redundant writer

This week I attended the TCANZ Conference 2010 in Wellington, New Zealand. Grant Mackenzie gave an awesome presentation entitled, “Video killed the redundant writer”. These are the notes I took during the session. All credit goes to Grant. Any mistakes are mine.

Grant has a great speaking style: relaxed, confident and with a light touch of humour. He gave his presentation on an iPad, which was interesting in itself. All went without a hitch. He asked us to put our pens down, put our brains in neutral, sit back and enjoy the ride. As his was the last session on a Friday afternoon, these instructions evoked a relieved sigh from the audience.

Here’s a neat quote from Grant:

Computer systems are basically binary code. Technical communicators are the final translators of what starts out as binary code.

It’s all about video

People in the coming generation don’t read manuals. They watch videos and source their information from the World Wide Web.

Websites

Grant suggested some websites to visit, for examples of interesting and good “how to” videos.

• Go to Howcast.com to see some great “how to” videos. It’s certainly an eclectic selection. Examples that Grant mentioned: How to have a shower; how to use a banana in seven unexpected ways; how to tell your parents you are unexpectedly pregnant.
• Go to CommonCraft.com and watch the explanation of augmented reality.
• Try the videos on ExcelTeacher.com.
• Screencast.com is a free hosting site from TechSmith. You can also embed the content from the hosting site onto your blog.

What makes an effective video?

Grant showed a number of short videos during his presentation, giving a convincing demonstration of how effective videos can be.

Videos must be compelling, to keep the viewers watching. What makes a good video? It must be:

• Short
• Relevant
• Pacy
• Genuine
• Findable
• Distinctive.

See the video from MsAppleUser: How to add right click on a Mac. This video satisfies most of the above requirements, Grant says.

Optional positives:

• Humour – but this can be risky.
• Show your face. See the video on how to use a web cam with Jing Pro. It drew laughs from the audience, and kept us engrossed.

What is a video?

Videos consist of containers and codecs. A container contains the codec. A codec contains the compressor and decompressor. The compressor reduces the file size for storage.

The people who watch the video need the same codec as the person who created the video.

There’s a link between video containers and file types. The name of the container and the file type are often the same. So, for most purposes, you can use the names interchangeably.

Grant’s tip: Just use MP4s.

Audio

Take care with the audio part of your video.

• Many viewers are hard of hearing. Make sure that you record at high volume. Set your microphone setting to 100% before you do any recording.
• Buy a high-quality microphone, the best that you can afford. Best is one that plugs into a USB port.

Tools

Grant recommends these your screencast, capture and edit tools :

• Microsoft Expression Encoder 4.
• Adobe Captivate 5.
• Madcap Mimic.
• Camtasia Studio 7. This is the one Grant uses. He recommends it if you don’t specifically want one of the above three to integrate with Microsoft, Adobe or Madcap products.
• Jing Pro. This one gets an honourable mention, because Grant loves it. It’s the best starter option. The Jing training videos are very cute! Note that you can’t edit anything in Jing.

Your video library

Plan the library in the same way as you would any documentation library.

How do people find content that is in a video?

• Try the VideoSurf add-on for Firefox. It shows stills of what’s in the video. You can click the link and go straight to the scene.
• You can create an interactive table of contents for the video, using tools such as Camtasia or Captivate.
• If you create a video from PowerPoint using Camtasia or Captivate, then the tool will automatically create a table of contents from the slide titles.

The wonders of PowerPoint

Grant says that PowerPoint is your friend, where videos are concerned. You can create a video using a screencast from PowerPoint. There are some great PowerPoint plugins. One is the Camtasia plugin, which Grant demonstrated during the session.

You can also just set PowerPoint to play, and record the slideshow with Jing.

PowerPoint gives your videos a consistent look and feel.

Consistency

A consistent look and feel is comforting for the viewers. If your videos have a consistency in the start and finish, your viewers will know they’re in the right place and will feel ready to learn.

Good examples are in the videos at TechSmith.com

Pros and cons of YouTube

Pros: It’s free. Videos are searchable and findable. Viewers watching your videos are using their own bandwidth. Anyone who has a computer can watch a YouTube video.

Cons: Some employers block their employees from using YouTube. YouTube uses its own compression algorithms, which can results in loss of quality.

Summing it up

In closing, Grant wanted us just to remember just 3 things:

• Turn your audio up to 100%.
• Make short videos.
• PowerPoint is your friend.

My conclusion

This was a really great presentation, full of humour and information. Thank you Grant!