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!
This week I’m at AODC 2010, the Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Matthew Ellison, the presenter. Any mistakes or omissions are my own.
An aside, and a reflection of the fun nature of AODC conferences: At the beginning of this postprandial session, we noticed that quite a number of people were absent. “Good time for a prize draw!” exclaimed Tony Self. (You have to be present to claim your prize.) As usual though, even with such improved chances, I did not win the prize.
Matthew Ellison‘s presentation today asked the question, “What Kind of Assistance do Users Really Need?” He introducted his talk saying that it was a good follow-on from mine. (I had given the preprandial presentation, about engaging your readers in the documentation. I’ll blog about it soon.) Matthew now followed through with providing the kind of assistance that users really need. To do that, he says, we really need to understand our users.
Matthew covered the following topics in this session:
- Background information and recent history that led Matthew to present this topic.
- Current trends in user assistance design — what we’re doing now and what we think our users need.
- Common traps for writers.
- Step-by-step instructions, and whether they are the best solution for users.
- A look at a research study that Matthew is involved in, and the results and recommendations coming from it.
Another aside: At this point Tony phoned Matthew on the mobile phone Matthew was using as a clicker! Hilarity broke out, as it so often does at AODC. Matthew, being an awesome presenter and well used to Tony’s antics, answered the phone with a grin and “Very funny, Tony” then returned to his presentation without breaking his stride.
Aims of UA
In this part of the session, Matthew took a look at the aims of UA (user assistance) or help. The principal aim is to solve problems and answer questions. Help can also make people aware of features and increase their efficiency in performing tasks.
At this point, Matthew asked us to think of the last time we had a question or problem and needed help.
I immediately thought of the problems I’d had with getting my internet connection to work at the hotel. “How do I get the hotel wi-fi broadband connection to work?”
The first 3 or 4 questions we came up with were all “how do I …”. Then a few different questions arose, such as “what is …”.
To illustrate the idea of cycles in design, Matthew showed some pretty cool pictures of bicycles 40 years ago, 20 years ago and today. The bikes of today share some design characteristics with the bikes of 40 years ago. In documentation and information design, ideas tend to cycle too. We looked at the recent trends towards FAQs and task-based help. Matthew thinks FAQs are a good thing. He showed us some examples of FAQs that work, including some from Twitter and YAHOO Groups.
Traps for technical writers
This may be a dangerous area, says Matthew. Some of the things he suggests are contrary to what he was originally taught about technical writing.
We should not:
- Just transcribe information given by developers and SMEs.
- Always give step-by-step instructions. Sometimes it’s enough to give just a simple hint or an answer to a single question.
- Explain the obvious. If it’s easy for us to understand, maybe we don’t need to document it.
- Blindly insist on consistency for its own sake.
Now there was another task for us: We had to write instructions telling people how to delete a file in Windows. Most of us chose to write step-by-step instructions. One group chose just a tip. Matthew suggested that you need a useful tip telling people to click Shift+Delete to remove the file permanently. You may also want to let people know that they can recover files deleted accidentally.
This simple exercise led to much animated debate, as might be expected from a group of technical writers. Is information ever redundant? :)
Matthew gave us an example of the way Apple have addressed the problem of explaining only the things that need explaining. See the iTunes help: “iTunes How To”. It contains a useful collection of tips people may need. For example, if you click “Buffer Sizes”, you get a page showing a screenshot of the buffer size dialogue and a short paragraph explaining what buffer sizes are and the implications of choosing a larger or smaller size.
Louise from PayPal
Louise is a PayPal “Virtual Agent”. You can type in questions and Louise will answer you.
Where do the responses come from? They’re composed by authors, based on typical questions asked by users. Tony Self, the organiser of the AODC conference, has in the past signed up as a “virtual person” and helped to write such answers. As a virtual agent, you see the questions that people typically ask and then you write the answers. You can select the personality of your agent, e.g. humble and kind or quirky and arrogant.
Some video tutorials are very bad, but some are good. As an example of a good one, Matthew showed us a video introducing Morae Observer. The voice is calm and make things sound simple. Each section is short. This video was created using Camtasia.
Study about the questions that people ask
Matthew has been taking part in a study at Portsmouth University in the UK. The reason for the study was the conviction that we should base our help on the questions that our users ask.
The study looks at when users ask questions and what types of questions they ask. It asks participants to tackle three tasks, each clearly explained. The explanation is about what the participant needs to do, rather than how to do it. There is a task in Word, a task using Google Maps (plan a route and view it in Street View) and a task using Flash.
The participants were not allowed to use the help. If they had questions, they had to ask the moderator sitting next to them. The moderator should answer only the question that was asked. This is known as the Wizard of Oz method.
Matthew and the university team used TechSmith Morae Observer to record everything that the participants did, including audio and video. This allowed them to analyse the participants’ actions and to draw conclusions.
The equipment they needed was simply a laptop with Morae installed, plus a webcam and microphone.
Results of the study
Note: Matthew explained that the results are only just becoming available. He can show us only partial, interim results at this stage. Also, I had to jot down the figures from Matthew’s live presentation, as they were not available at the time the slides were printed for our handbook. I’ve done my best to get them right. Matthew will publish the final results later.
The study classified the questions that users asked into 7 categories:
- Meaning (What does this mean)
- Reason (Why is this happening, or why should I do this)
- Confirmation (Is this what I should be doing)
- Location (Where do I go to do this)
- Task (What do I do now, or how do I do it)
Based on 7 participants out of 20, here is the number of questions that fell into each category:
- Meaning: 8
- Reason: 3
- Confirmation: 74
- Location: 27
- Task: 49
- Response: 3
- Identity: 3
Participants often had trouble framing the question. Imagine how difficult it would be for them to ask the question online instead of to a person.
There was a surprisingly large number of questions in the “confirmation” category. Some participants often asked for confirmation or affirmation.
There were very few questions that fell into the reason, identity and response categories.
Conclusions — interim only:
- Tasks are the most common question type.
- Location is the key to solving the problems.
- Meaning and reason are not very important in this particular study.
Matthew will publish the final results when available.
Matthew strongly encourages us to do a similar exercise. It is hugely enlightening to see how people tackle a task and the questions they ask.
This session was a lot of fun, especially because of the interaction between us and Matthew, and because of the lively discussions that arose. I’m looking forward to seeing the full results of the study and will publish a link as soon as it’s available. Thank you Matthew for a very interesting session.
This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. Crocs and docs, what more can you ask for! This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Tony Self, the presenter. All the mistakes and omissions are my own.
After a busy, informative and fun-filled morning on Wednesday, we broke for lunch. Then Tony Self presented the first afternoon session, called “An Update on DITA Features, Tools, and Best Practices”.
Here’s a photo of Tony. I took it on Thursday morning when he was presenting another session. (I thought I’d better mention that, because he’s sure to notice that he’s wearing his Thursday shirt!)
Tony’s talk covered these topics:
- An overview of DITA: authoring, content management, publishing tools and the DITA Open Toolkit.
- A preview of the features in DITA 1.2.
- The usefulness of specialisation and constraints.
- DITA as used in various help-authoring tools (affectionately known as HATs).
- Delivery options for content authored in DITA.
Introduction to DITA
Here are my key takeaways from this part of Tony’s session:
- DITA is an OASIS standard for a form of XML.
- DITA is a semantic markup language. There are no presentational elements. This enforces the separation of content from form.
- When working with DITA, you use a suite of tools rather than a single tool. So for example, you may use an authoring tool for DITA, a separate publishing tool for DITA, another tool for reviewing content, and so on.
Some examples of authoring tools:
- XXE (XMLmind XML Editor)
- DITA Storm
Interestingly, the DITA Open Toolkit is not on the list. The toolkit does not offer an authoring tool.
A hint: Because DITA is a standard, you can use the authoring tools interchangeably. The content is stored in exactly the same format.
Some CMSes are DITA aware:
- Xdocs can use XMetal, XXE or oXygen
- Ixiasoft DITA CMS
- SDL Trisoft
- Siberlogic Sibersafe
Author-it is not on the list, because it can’t manage DITA content.
Other DITA tools:
- XMetal Reviewer (an addon to XMetal)
- Leximation DITA-FMx (a FrameMaker plugin)
- Content Mapper for Information Mapping
Publishing or rendering tools:
- MadCap Flare (Flare is not an authoring tool. You can import your DITA content into Flare and then output it into another format such as HTML.)
- RoboHelp (As above, RoboHelp is not an authoring tool.)
- Antenna House
- XMLmind DITA Converter (ditac)
- DITA Open Toolkit
- WebWorks ePublisher
- WinANT Echidna (Tony created this tool.)
- Arbortext Publishing Engine
Pricing varies considerably. Some tools are free and opensource. Others are commercial and quite expensive.
DITA working with help authoring tools
These are some of the points Tony covered around DITA and HATs:
- None of the common authoring tools are DITA editors.
- Some are good DITA publishing tools (in particular, Tony mentioned Flare an RoboHelp).
- WebWorks ePublisher supports DITA content.
- Author-it allows you to export your content into DITA format. Note that it exports generic DITA content, not the full semantic markup.
- With RoboHelp 8, you can import DITA content.
- Flare 5 supports the import and export of DITA content. It does not support a round trip.
Delivering DITA content
DITA Open Toolkit can convert DITA to:
- HTML (XHTML)
- HTML Help (CHM files)
- Eclipse Help — Tony gave us a quick demo of an Eclipse Help help system. He was running an Eclipse standalone web server from his own machine.
Commercial tools can convert DITA to WebHelp, AIR Help, ePub (eBook format) and many others.
There also plugins for the DITA Open Toolkit, dubbed OT plugins, that can produce:
- Simple WebHelp
- Context-sensitive help (Eclipse Help and CHM i.e. HTML Help)
- AIR Help
- eBook content
Increasing demand for different help formats
Tony pointed out that more and more user assistance is being delivered on “unusual” media such as phones, tablets, GPS displays, eBooks and augmented reality goggles. One of the beauties of DITA is that the separation of content from representation makes it easier to support a multitude of output media.
Tony’s verdict: Is DITA ready for us to produce professional online help?
If you’re looking for tri-pane help output such as HTML, HTML Help and Eclipse Help, you can do that with the OT.
If you want professional-looking output, you can do that with some work on the CSS style sheets
If you need context sensitivity, you can do that too with a bit of extra work.
But DITA is not quite ready for more sophisticated features such as popups and dropdowns.
In this part of the talk, Tony went into the new features of DITA 1.2. I didn’t take detailed notes here. Tony has a lot of information and I’m sure he’d be delighted to pass it on.
One of the bits I found interesting was that there’s been some criticism of DITA 1.2. Some people say DITA is becoming more and more flexible (“sloppy”) and therefore less and less useful, in that you can now add new types of <div> to the DITA “task” topic type. When you upgrade to DITA 1.2, your task topics will automatically become “sloppy”. If you like, you can “constrain” them to make them more strict.
Also pretty cool in DITA 1.2: The new “subjectScheme” ditamap element supports facets, a concept discussed in Matthew Ellison’s earlier session on search. (I’ve blogged about Matthew’s session.)
The DITA 1.2 standard has not yet been officially released. Even so, some tools support it already:
- Open Toolkit 1.5
Choosing a tool
Tony gave us some points to consider when choosing a DITA authoring tool:
- The tool should be as compliant as possible i.e. it should support the current DITA standard.
- The tool should support the round trip, so that you can open DITA content, work on it and then save it as DITA.
- You need a tool that supports specialisation, so that you can add your own topic types.
- It’s good to have a tool that is as open as possible, so that it is extensible and interoperable.
Thank you Tony for a useful update on the current state of affairs in DITA world. In particular, Tony has given us some great information on the tools available. For me, as someone who does not use DITA but is interested in the technology and its aims, it’s really useful to get a quick blast of information in this way.
This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the first day of the conference.
Here are some notes I took from the session on the changing language and technologies of communication, by Tony Self of HyperWrite. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.
What if the reader can’t read?
In this presentation by Tony Self, the theme was the changing language and technologies of communication. He gave us a number of things to think about and gently nudged us towards the ways we might need to change in order to continue working in the technical communication field.
He asked us to think about our readers, the most important people in our world. Our “typical reader” is changing. A good way to see what they might look like is to examine our university undergraduates. They’re the people entering the workforce now.
Tony showed us a video about a survey of students at Kansas State University. For this online survey, 200 cultural anthrolopology (digital ethnography) students edited the survey page themselves, and made 367 changes to it. So this means that they surveyed themselves. Here’s some of what I deduced from what the students wrote:
- They spend much of their time online.
- They multi-task.
- They’re concerned about the wider world’s problems.
- They read Facebook and other online stuff during class.
The survey showed that the average university student read 8 paper books per year, but 2300 web pages and 1281 Facebook profiles. The average student also wrote 42 pages of assignments but 500 pages of email.
Tony says the way we communicate is changing, and also the rules of language are changing. What’s more, the accepted rules of grammar are no longer so important.
These are some of the points Tony raised, about the way people communicate and their attitude to communication:
- 11% of year 7 students lack basic reading skills.
- There’s a lot of reading and writing done on mobile phones, via SMS and via instant messaging (MSN).
- The so-called “txtspeak” or “txt speak” or “text speak” ignores the rules of grammar and spelling.
- In New Zealand since 2006, students can use text speak in national exams. Their answers must still demonstrate the required level of understanding.
- Younger people have an entirely different attitude to copyright and privacy. They know about plagiarism, but they’re not sure how to integrate other people’s content into their own e.g. a page off Wikipedia. The boundary between private and public is different. They might treat their Facebook page as “private” even though it’s open to their friends. And the term “friends” here means something else too.
- Information overload is commonplace. They encounter as much information in a year as their grandparents did in a lifetime.
- They’re accustomed to information becoming obsolete.
- They’re used to sharing their knowledge instantly and virtually. So instead of reading manuals, most of them learn how to use something (e.g. their mobile phone) by talking to their friends.
Also, Tony noted, it’s not just the young folk. Readers are becoming more impatient. Readers will spend about 4 seconds on a web page, in order to decide whether it’s worth reading. That’s about 15 words. So we have to be very careful about those words, and we have to be minimalist.
People tend to power-browse horizontally through titles, content pages and abstracts. They read snippets of text from different sources, rather than going for in-depth vertical information.
Things are changing rapidly, and we can’t just ignore this fact. So how are we going to communicate with people who communicate in this way?
Tony took a look at other technologies and how they are adapting:
- Print media is changing. Take a look at the “Express News” in Melbourne’s The Age newspaper. Also “Shortcuts” in the New York Times. Readers can just read short summaries in two columns, rather than reading the whole newspaper.
- TV is changing — current affairs programmes spend just a few minutes on a topic, giving superficial coverage, then move on to the next one.
- Politicians are shortening and targeting their communications too.
So, what can we do in technical communication?
- Move to topic-based authoring — allows for horizontal skimming.
- Embrace minimalism (the 15 words rule).
- Take advantage of blogs, wikis and other new media.
- Adopt single sourcing, so that we can produce our documents in different forms that suit different readers.
- Reduce production time.
- Consider abandoning the table of contents. Tony says that the TOC may no longer be a valid way of navigating. Instead, we should pay attention to search.
- Drop task information in software manuals. This information should be conveyed intuitively in the UI. Instead, the manual should concentrate on concept-based information.
- We should look at new ways of communicating concepts, such as graphical. Tony told a story of how he tried to find information on how to reset his iPod Nano. He could not find the information from Apple. He eventually did a Google search, which sent him to a YouTube video showing exactly what he wanted. This video was made by a 15-year-old boy, who had filmed himself resetting his Nano. Tony was learning from his peers, not from Apple. This is the way most people do it now. People collaborate, and trust that the information is good.
So, if the user’s peers are creating the help guides, where do we fit in? Maybe our role is to facilitate this communication, not to write it. We should experiment with alternative communication techniques. Could our manuals be video, or podcast?
The questions at the end of Tony’s session were interesting too:
- How do we to manage version control and obsolescence if our information is spread out on sites such as YouTube? One answer was that the rating of the obsolescent information would be lower, and people would understand that the older information related to an older version of the product. (I think this is somewhere that technical writers can contribute. For example, we can ensure that the information is clearly marked with the version information. And we can design a storage/serving system that categorises the videos or podcasts so that it can serve multiple versions of the document, depending on the product version required.)
- In this context, Allyn mentioned the s1000D standard, which tells you how to structure content appropriately, developed to serve the aircraft industry, where it’s extremely important to get the right version of the documentation. (Dave Lowe will talk about this in a later AODC session.)
- Another person from the floor said that “blended learning” is the way to go. Most people prefer to watch a video because they don’t have time to read a document. Others prefer to read a document. So we need to offer a blended solution.
Thank you Tony for a very interesting session.