AODC day 2 – Stump the panel
This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the second day of the conference. Here are some notes I took from the “Stump the Panel” session.
Responding to feedback from previous AODC conferences, Tony Self has set up a session where people can ask questions freely. He has appointed a panel of experts to field the questions. Also, people on the floor may be able to answer questions, because we’re all experts in specific areas.
Stump the Panel
Here are some of the questions and answers I found interesting. I’ve noted down the question and some of the answers in each case. Where I could, I have given the person’s name. Otherwise I’ve used the word “floor” to indicate an answer that came from someone on the floor. Please forgive me if I’ve misquoted anyone 😉
1) Managing multiple authors all over the world
“I need to change to topic-based authoring. My authors are all over the world, and I won’t meet them. They’re not all English-speaking. They’ll work with me for just a couple of weeks. How do I persuade them to write in the way I need them to write? How do I approach them and which tool do I use?”
- Monica: We have a similar situation. We have set up templates. Most authoring tools have the ability to create a template. Give your people templates, give them the ground rules, and have a QA process.
- Dave: Use a controlled language, so that you have a defined vocabulary that everyone will use. This will help to standardise the topic content.
- Monica: Do an example i.e. a mockup so that they can see what their end product should look like.
- Deborah: Sometimes you just have to edit the content yourself to put it into the format you need.
- Floor: Agreed. The QA process is necessary and is just manual work. There’s no magic bullet to get around this.
- Tony: At another site, the engineers were asked to provide the information via a web-based form. The information was then extracted and put into DITA via XSLT.
- Floor: Try phoning people personally, or hold a conference meeting or webinar. Often real live contact is the best way to explain what’s required. You can record the webinar into a movie, so that other people can watch it later.
2) Tool for managing content by multiple authors all over the world
” I too have writers based all over the world. We need a tool to (a) single-source properly, and (b) share content with writers in different locations.”
- Deborah: You can probably use any old SCM e.g. SVN. The trouble is, they only deal with files.
- Floor: Microsoft Live Folders lets a group of people connect to online folders. It’s a desktop application that syncs to an online file storage service.
- Floor: RoboHelp has a built-in source control, and can integrate with Microsoft Visual SourceSafe (VSS).
- Floor: Immedius Horizon — Includes an integrated XML authoring tool too.
- Deborah: A hint — Make sure the tools work in your environment, especially with respect to performance and especially if you have users distributed in different locations.
3) Virtual learning environment for multiple age groups
“Assume you have a virtual learning environment for schools, used by students and teachers. Now you need to design a help system for the VLE. How can the help system accommodate all the age groups of the students (6-17 years)?”
- Tony and Matthew: Referring to the help for Lego — It did not contain much text. Same as for the help for games. Instead, you learn by solving a challenge. So you start with the easy tasks and move on to the more challenging tasks.
- Floor: Divide the content into bands by age group, so that you can hide some content (e.g. sex education) from the younger children. This is a great opportunity for topic-based help.
- Floor: There are some good tools coming out for automatic generation of meta data e.g. “Automatic Metadata Generator (AMG)”.
4) Microsoft Help 3
“Has anyone heard anything about Help 3?
- Tony: Help 3 is another Microsoft initiative, basically an HTML-based help system with lots of metadata. But they did not look beyond Microsoft at first, for version 3.0. They’re now working on 3.1 and thinking about DITA. In the general technical communications community, people are not too excited about it yet. One of the ways for finding information about it is via Facebook.
- (A note from me when writing this blog post: I attended the WritersUA session where Microsoft’s April Reagan discussed Help 3. Here’s my blog post.)
5) Different versions of the documentation for different business areas
“We’re using RoboHelp, Word and .chm files. We’re running into the problem where each area of the business needs a slightly different version of the document.”
- Floor: RoboHelp has conditional build tags. You can add as many conditional help tags as you need.
- Floor: I use Word styles to tag conditional content, and then use macros to eliminate the text I don’t want for a particular version. I also colour the background of the conditional text. This is very easy to maintain.
- Floor: We use Author-IT which caters very well for conditional text e.g. when you need a Windows version, a Unix version, etc. We moved from RoboHelp to Author-IT a few years ago.
6) Updating screen captures after a change in UI
“If you have recorded a whole series of screen captures and then the UI changes, you have to re-do all the screen captures. Are there any tools to help with this?”
- Deborah: There’s an old tool called Rational Robot. There are newer tools of the same kind too. They’re the sort of tools used by QA departments. They’re also useful when you’re documenting a UI in different languages. Basically, they hook into specific IDs on the UI. These should work for screen captures too.
That’s the end of “Stump the Panel”. Thank you panel.