A couple of weeks ago I was in Darwin – ya know, that place where evolution started. It’s a bit warm up there. The insects are the size of Sydney’s birds. The spiders are the size of Sydney’s fruit bats. Crocodiles lunge out of the drains and grab your ankles. Technical writers lurk under banyans swapping tales of DITA, dragons and eggcorns.
I was attending and presenting at AODC 2010, the 13th Australasian Online Documentation and Content conference. This is the third AODC conference I’ve attended, and all have been awesome. Tony Self, the organiser, has the knack of selecting interesting topics. More than a knack, I suspect it comes down to lots of hard work. The speakers and attendees alike are knowledgeable and enthusiastic technical writers, making for a great all-round experience.
This year’s conference spanned three days and eighteen sessions. I attended every single session, even the one that started at 8am on Thursday! I’ve written summaries of most of them, as linked below:
- AODC day 1: Turning Search into Find
- AODC day 1: The Power of Controlled Language
- AODC day 1: An Update on DITA Features, Tools and Best Practices
- AODC day 1: UA Design and Implementation for iPhone App
- AODC Day 2: Managing a Documentation Project
- AODC day 2: A Beginner’s Introduction to DITA
- AODC day 2: Engaging your readers in the documentation
- AODC day 2: What Kind of Assistance do Users Really Need?
- AODC day 2: Optimising your Content for Google Search
- AODC Day 3: Converting to Structured Content
- AODC Day 3: Introduction to DITA Conditional Publishing
- AODC Day 3: Help Authoring Tool Comparison
- AODC day 3: I can’t spell Ambliance
These were the sessions I didn’t write notes for, or where my notes are too disorganised to compile a blog post from:
- Networking. This happened on the first day, and was a lot of fun. We divided into groups, based on random criteria devised by Tony, had a quick chat with our group then hustled to form the next groupings based on even more random criteria.
- The Wonders of SVG, by Tony Self.
- WinANT Echidna – The DITA Open Toolkit Made Easy, by Tony Self.
- A Walk through Google Apps, an interactive session led by a panel of experts.
- Creating Auto-Magic TOCs with XSLT, by Dave Gash.
Fun and networking
The conference is infused with fun and liberally sprinkled with grains of Tony’s inimitable humour. At one stage early in the proceedings, when Tony was introducing a session, a ribald and fairly loud comment came from the back of the room. Tony’s response was instant:
“For the new people: That’s Choco. Please ignore him.”
Of course, in real life Choco is a professional and dedicated technical writer and author. He’s also entrusted with the important task of presenting the final AODC session.
Here we’re looking uncharacteristically studious, waiting for one of the sessions to begin:
At one stage Tony announced, “There’s gold class seating at the back. We bring you your tea and coffee if you sit there.” True enough! Here’s Dave in said gold class seating. I don’t think the tea or coffee ever materialised though:
On Thursday night we all trooped down to the famous Mindil Market. The market is one of Darwin’s not-to-be-missed attractions, happening every Thursday and Sunday evening during the dry season. The thing to do is to grab a meal and a smoothie from the market stalls, then mosey on down to Mindil Beach to watch the sunset. You may recognise a few AODCers in these silhouettes:
If you’d like to see more pictures and words about Mindil Market and Darwin, take a look at what the Travelling Worm has to say. He was there at AODC too, strictly under cover of course. He did valiantly stand between me and a crocodile or two.
Uncle Dave’s Trivia Night
No AODC conference is complete without it. I’ve devoted a whole blog post to Uncle Dave’s Trivia Night.
More photos on Flickr
I’ve uploaded a set of AODC photos on Flickr. If anyone has any more photos, please add a comment to this post, linking to your photos. I’d love to see them!
See you at AODC 2011
I’m looking forward to next year’s conference already!
Last month I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. Over the last couple of weeks, I’ve been posting my summaries of the conference sessions, derived from my notes taken during the presentations. All the credit goes to the presenter. Any mistakes or omissions are my own.
Frank “Choco” Munday presented the last session of the conference. Choco is an awesome presenter. It’s something of a tradition (the AODC has a few of those) that the conference ends with a raucous laugh. Choco excels at putting that sort of finishing touch to an event!
In this presentation, we looked at some horrors that technical writers may encounter and indeed should do our utmost to avoid.
“Eggcorn” is a linguistic term for the practice of replacing a complex or scientific term with a more commonly-used word, especially when people swap the unfamiliar part of a phrase with a word that occurs more often in their own dialect. An oft-quoted example is the use of “old-timers disease” instead of “Alzheimer’s disease”. Wikipedia says that the term “eggcorn” was coined by Geoffrey Pullum in 2003, based on a case where a woman used the phrase “egg corns” when she meant “acorns”.
Choco was specifically concerned with “eggcorns” as spell-as-you-speak errors. He took us through a rollicking and somewhat scathing look at a number of eggcorns, such as:
- “Should of” for “should have” – a frequent occurrence in Australia.
- “At your beckoned call”.
- “For all intensive purposes”.
- “I think I might be lack toast and tolerant” for “lactose intolerant”.
Choco showed a number of examples from print and online media, and lambasted them thoroughly. It’s well worth getting him to run through his list with you.
Next Choco turned his eagle eye to mixed metaphors. Politicians were worth their weight in gold here.
Choco said, “I would slip one or two into my technical documentation, just to see what happens”. (Mixed metaphors, that is, not politicians.)
Unwords got some Choco love too. Choco suggests we take a look at the Unword Dictionary at unwords.com.
So I did that. Here’s an unword I like:
19. bandpulliphobia (bănd-pu’lə-fō’bē-ə)
- a. (n.) The fear of pulling off a band-aid; Especially when counting down from three.
Remembering that we were attending a serious technical writing conference, Choco did mention with a straight face (for a split second, anyway) that unwords are words that are not really words, so there’s a chance that people won’t understand them. We should therefore avoid them in our technical documentation. I was glad of this reminder, as I was starting to feel the temptation.
A fittingly boisterous end to AODC. Fun, but with a serious undertone. Thank you Choco.
A couple of weeks ago I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. This post is my summary of one of the sessions at the conference and is derived from my notes taken during the presentation. All the credit goes to Dave Gash, the presenter. Any mistakes or omissions are my own.
This year’s AODC included a number of useful sessions on DITA, the Darwin Information Typing Architecture. I’ve already written about Tony Self’s session, an update on DITA features and tools, and about Suchi Govindarajan’s session, an introduction to DITA.
Now Dave Gash presented one of the more advanced DITA sessions, titled “Introduction to DITA Conditional Publishing”.
At the beginning of his talk, Dave made an announcement. He has presented in countries all over the world, many times, and he has never ever ever before done a presentation in shorts!
Introducing the session
To kick off, Dave answered the question, “Why do we care about conditional processing?” One of the tenets of DITA is re-use. You may have hundreds or even thousands of topics. In any single documentation set, you probably don’t want to publish every piece of the documentation every time.
Conditional processing is a way to determine which content is published at any one time.
Dave’s talk covered these subjects:
- A review of DITA topics, maps and publishing flow
- The use of metadata
- The mechanics of conditional processing
- Some examples
Metadata and the build process
Dave ran us through a quick review of the DITA build process and the concept of metadata. Metadata has many uses. Dave talked specifically about metadata for the control of content publication.
Metadata via attributes
There are a number of attributes available on most DITA elements. These are some of the attributes Dave discussed:
- audience – a group of intended readers
- product – the product name
- platform – the target platform
- rev – product version number
- otherprops – you can use this for other properties
Using metadata for conditional processing
Basically, you use the metadata to filter the content. For example, let’s assume you are writing the installation guide for a software application. You may store all the instructions for Linux, Windows and Mac OS in one file. When publishing, you can filter the operating systems and produce separate output for each OS.
In general, you can put metadata in these 3 locations (layers):
- maps – metadata on the <map> element. You might use metadata at this layer to build a manual from similar topics for specific versions of a product.
- topics – metadata to select an entire topic. You might use metadata at this layer to build a documentation set for review by a specific person.
- elements – metadata on individual XML elements inside a topic. You might use this metadata to select steps that are relevant for beginners, as opposed to intermediate or advanced users.
Dave gave us some guidelines on how to decide which of the above layers to use under given circumstances.
Defining the build conditions to control the filtering
Use the ditaval file to define the filter conditions. This file contains the conditions that we want to match on, and actions to take when they’re matched. The build file contains a reference to the ditaval file, making sure it drives the build.
Dave talked us through the <prop> element in the ditaval file, and its attributes:
- att – attribute to be processed
- val – value to be matched
- action – action to take when match is found
A hint: You can use the same attribute in different layers (map, topic and element). Also, you don’t need to specify the location. The build will find the attributes, based on the <prop> element in the ditaval file.
Next we looked at the “include” and “exclude” actions. Remember, the action is one of the attributes in the <prop> element, as described above. Here’s an example of an action:
<prop att="audience" val="novice" action="exclude" />
Dave’s recommendation, very strongly put is:
Don’t use “include”. Stick to “exclude”.
The basic rule is: Everything not explicitly excluded is included.
Dave’s final recommendation
Go get DITA and play with it!
It was great to have a focus on the conditional publishing side of DITA. It’s something I haven’t had a chance to get into before. Now I know the basics, which rounds off the DITA picture for me. Thank you Dave for an entertaining and information-packed talk.
Over the past few days I’ve posted a number of sober, studious, serious summaries of the sessions at AODC 2010. “A three-day technical writer talk fest, yawn.” Not so! On occasion we do break out and indulge in a trivia night.
Uncle Dave’s Trivia Night is an AODC tradition. It happens in the evening of the conference’s second day, usually a Thursday, and attendance is compulsory. Well, it’s as compulsory as anything at AODC. It ranks up there with the AODC rules, read out dutifully by Tony or Dave at some random time during the conference. “No swearing”, “no mobile phones” and “no hooking”. Almost all the rules are merrily ignored.
Anyway, I digress. (Digression is of course encouraged at AODC. I would win a bonus point for it at Trivia Night.)
The Trivia Night trophy is of incalculable value and much coveted. It’s a fully automatic, magnificently functional antique shoe shiner. You can get some idea of its value from the way Tony holds it as he shows it to us awe-struck trivia devotees:
Of course, the winning team gains the privilege of having their name engraved on the trophy for all eternity:
Dave Gash is the intrepid compiler of the questions and the hero of the night. Here he is, introducing the first round (of questions, that is, though beer was well represented too):
We divided into teams of four or five. (Numbers are approximate, just like quantum physics.) I was in the best team of the night. As you will see, we excelled throughout and in every way. To begin with, we chose the name “Team Rocket”. Judging from Tony’s expression when we announced our name, it was not a good choice. And so it turned out. Tony deducted a point from our score immediately, for a poor choice of name!
Tony is the judge, final arbiter and awarder of points. Scrupulously fair, benevolently strict, unfailingly impartial and completely incorruptible, the judge responds well to a free beer or any other suitable bribe.
The other teams were the “Mindel Maniacs” (boo, hiss), the “Dribbling Scribblers” and the infamous, annually-sprouting “Farkin Iceholes”.
The trivia quiz consists of 5 rounds, each containing 8 questions. Then there’s that final, 41st question where fortunes are gambled, lives are won or lost, and strategy is all. You can wager all or part of your total score on that single last question. If you get the answer right, the number of points you wagered is added to your score. If you get it wrong, the number is deducted from your score.
Round 1 came in with a bang. Team Rocket scored a big fat zero. We also lost a point for being slow. We did temporarily gain a point because our team name had become amusingly ironic. Alas however, in the face of our judge’s unmistakable disappointment at the original name, we had sneakily changed it to “Pocket Rockets”, so we lost another point for that deception.
To our utmost surprise and no little pleasure, Tony then awarded us a round of drinks. “Why?” came our started cry. As encouragement, was the reply. Our total score was now -3 points + 4 drinks. I think I lost count somewhere along the way.
During the proceedings, the Dribbling Scribblers lost a point for attempting to bribe the judge. The amount offered, 50c, was considered demeaning.
By the end of round 3, the Pocket Rockets (aka Team Rocket) had managed to bring our score up to the grand total of zero. In round 4, we scored 7 points (wow!) and gained a bonus point by bribing the judge with some jelly beans:
And now the decider! It was time for that all-important, win or lose last question. Our total score was 13-and-a-half. The Dribbling Scribblers had 16. The Mindel Maniacs (boo, hiss) had 22-and-a-half. The Farkin Iceholes (it got funnier and funnier through the evening as Tony and Dave tried to pronounce this name politely) had 24.
Strategy is all. We wagered 13 points, got the final answer wrong, and ended up with a grand score of half a point. The Mindel Maniacs (who?) were the only team who got the answer right. They won the contest with a total of 42 points.
Here’s Dave with the winning team (what was their name again?) and the magnificent trophy:
Here’s Team Rocket (aka the Pocket Rockets) proudly displaying our prizes for coming last. We were instructed to look disappointed, but only Matthew could pull that off:
Wanna know what we won? A coaster, a pen and a sweet. The sweet was an afterthought:
Dave paid us the final accolade:
You played a hell of a game!
I think he meant it sincerely.
The end (but not really)
If you came here looking for the serious side of technical communication, you’re in the wrong place. Ha ha, just kidding. I’ve already posted a number of summaries from this great AODC conference and there are still a few more sessions that I want to write up, including my own. Coming up just as soon as I find the time to convert my notes into blog posts.