Blog Archives

Two Australian tech writing conferences just around the corner

Are you in or near Australia in October and November? Then you’re in for a treat. We have two technical writing conferences in a row, within a stone’s throw of each other. Well, for some definition of “stone’s throw”, anyway. 😉

First up is the annual conference of the Australian Society for Technical Communication, which takes place in Surfers Paradise on 12-13 October. The conference theme is Let’s get technical, technical. Learn about CSS smart selectors, rethinking DITA, speeding up your web pages, blockchain, impossible docs, becoming an efficient writer, Simplified Technical English, and more. Follow up with a focused workshop on web coding. Check the list of presentations and fill in the registration form.

Next up is the Write the Docs AU conference in Melbourne on 15-16 November. This is the second WtD AU conference ever, following on from last year’s debut. This event offers a mix of presentations, lightning talks, workshops, and unconference sessions. Check out the schedule and get a ticket.

Found on a walk in the bush – patterns on the bottom of a squashed mushroom. Intriguing:

Technical Communicators Conference 2017 wrapup

This week I attended the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a summary of my impressions of the conference, with links to the posts I’ve written about each session.

I thoroughly enjoyed this conference, with its atmosphere of dedicated professionalism mixed with warm friendliness. The event took place in Sydney, Australia, filling two days with 14 technical sessions. By my rough estimate (I counted the tables at lunch) there were around 60 attendees. Most were from Melbourne and Sydney. A few people flew in from New Zealand, one from the west coast of Australia, and one from the US. Let me know if I’ve missed out any other travellers from far-flung places!


As is often the case with conferences, one of the best parts was meeting and talking to people face to face. Many were old friends whom I’ve met at other gatherings over the years. It was also great to make new friends.

A common theme arose in my conversations with the other writers. Those who have a role in a company or organisation find that there’s way to much work for them to handle. Even if they’re lucky enough to work with one or more other writers, there’s still a firehose of work pouring down on them. (This wasn’t so much the case with the writers who run their own businesses.) The people I spoke to said it was a good position to be in, yet at the same time they wished the organisations would allocate more budget and/or make more tech writing positions available. The writers feel strongly that they’re making a large contribution to the customer experience or process efficiency of their organisation, and could improve things even more if there were more writers around.

I think this sentiment is a very positive trend. Tech writers recognise their worth and feel that they’re doing valuable work. There was no frustration in the way people spoke. No-one said that their work went unrecognised within the organisation. They just wished there were more of them around.

The nice thing about a smallish conference is that you meet the same people more than once during the course of the two days, and can build up a relationship with them over that time. Most people attended all the sessions (there was only one track). People exchanged opinions enthusiastically during and after the sessions. During some sessions there were even jokes flying around between presenter and audience members.


Here are my posts about the sessions, in reverse chronological order, with the conference’s last session at the top of the list:


Thank you so much to the ASTC committee and the conference organisers, for all the hard work you’ve put into this conference. It was excellent. Thanks also to the presenters who put so much time and energy into preparing and presenting the talks.

Yes but I have my phone – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Grant Mackenzie presented a session with the enticing title of Yes but I have my phone. I didn’t take any notes during this talk, as the conference organiser asked us to put away all pens and laptops. The point of the session was that you can do everything with a mobile device. I guess I could have taken notes on my phone, but somehow that seems to me like I’m paying less attention to the speaker than when I’m using my laptop. Something to do with the focus of attention and the posture required to take notes on a tiny screen. Entering text on a mobile screen also takes more time than typing, even though I’m an adept swiper. In fact, I’m writing this post on my mobile device, while on the bus on the way home from the conference. So, for me anyway, this is one use case when a laptop, or at least a keyboard, is better than a mobile screen.

Back to Grant’s presentation, which was lively and packed with information. The main thrust of the talk was that you can use a mobile device to create engaging, informative content. In particular, Grant demonstrated the use of various apps to create professional videos and photo-based art, complete with green screen effects and good audio.

Release notes came up again – they’ve been popular in this year’s conference. Grant’s approach is to have two important people in the company talk through the items in the release notes, while illustrating the features on screen, either behind the speakers by use of the green screen, or fullscreen using the speakers’ words as voice over.

We also saw some cat videos. 🙂

Thanks Grant. Your presentation was a thing of beauty.

The vibe of XSL-T at ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Tony Self presented a session called The Vibe of XSL-T. Tony’s plan is to show us where XSL fits in the XML universe, and then where XSL-T fits in and where it’s useful. He demonstrated, by asking the audience, that most of us were using XML to store at least some of our content. Another of Tony’s goals is to discuss the level of expertise we need, to use XSL-T.

What is XML?

XML is a format for storing information.

XML tags are generally semantic, which means a human being can generally understand its purpose by reading it. Unfortunately, some designers of XML documents don’t necessarily follow that best practice.

Tony edited a .pptx file (a PowerPoint presentation) in a text editor, and demonstrated that you can change the content of a presentation by editing the XML as a text format. Understanding that Office documents are essentially XML underneath gives you some power.

The help format known as .chm is also an XML-based format. Internet Explorer, which has been able to render XML for years, can therefore render the content.

XML is a common way of storing information. A useful ramification is that you can write reports based on the XML.

XML is more like a family of languages rather than a specific language. It’s a set of rules for creating a language. Most XML languages are semantic in nature, in that they define concepts such as dogs, breeds, height, weight, and so on. There are standards for creating XML languages, and strict validation rules to enforce them. The rules are stored in a DTD (document type definition) or an XSD (schema definition). XML is Internet-friendly. The XSD, XSL, and XML files can all be stored in different location.

The rules and standard patterns mean that all tools that understand XML can also understand all forms of XML. For example, editors, browsers, VCRs.

What is XSL?

There are a few types of XSL:

  • XSL-T: transforms a document from one format to another, where the format is some form of text-based content. XSL-T  determines how the data is arranged, which data is omitted, and so on.
  • XSL-FO: transforms a document to some type of page-oriented medium, such as PDF. For example, you can convert a file to Apache-FOP and then PDF, using a process controlled by Ant.
  • XPath: finds information in an XML document. You use it to navigate through elements and attributes in an XML document, and retrieve the part of the document that matches your search criteria.

More about XML

XML is beautifully organised, making it simple to use. Most of the XML standards are still in version 1, a testament to the care taken with the original design.

Tony walked us through some examples of XML, and of using XSL-T to transform a document into an HTML page.

Thank you Tony for a good overview of XML technology.

Writing micro-content – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Margaret Hassall presented a session entitled Writing micro-content, or Writing content for people in a hurry. She talked about headings, Twitter, and content.

We need to figure out whether people are reading our content, and how much of it they’re reading. Take into account the fact that people scan content. Margaret touched on Nielson’s research on eye tracking, showing the areas of a page on which people spend most time.

Even given the new technology like Twitter and mobile phones, the basic principles of content creation haven’t changed. Be concise, and consider your audience. People just want to get in, get the information, and get out. Push for plain language and fewer words. Add headings, shorten your sentences, add pictures. Most importantly, figure out your audience and write for them. Consider why they need the release information.

Margaret’s pet peeve is release notes. When reading release notes, readers want to know what’s changed and how the change affects them. Many release notes are full of content and make the relevant information hard to find. Margaret walked us through some examples of release notes, pointing out good and bad aspects of each, from a technical communication point of view. Comments that came up:

  • The order of the issues listed in the release notes. Should the items be in order of the issue number, the description, other…?
  • Grouping of issues by category.
  • Clear indication of whether the item is about a feature or a bug fix.
  • Inclusion of a bug number for reference.
  • Link back to the issue tracker.
  • Changing of the description, so that it no longer matches the original issue description. This can cause a problem for customers who can’t match the fix against the reported problem.

Margaret discussed the possibility of including tech writers in issue management. We could, for example, write better titles or better descriptions. Sometimes the title of the bug describes the problem as understood by the user, but when the issue is fixed, we find that the title no longer adequately describes the problem.

It all boils down to considering your audience and why they need the release information, then presenting the information to them in a clear, concise document.

Margaret also touched on headings in a document, and on subject lines in email messages.

Thanks to Margaret for these interesting insights into release notes and other documents that people are likely to read in a hurry.

%d bloggers like this: