Category Archives: AODC

AODC 2010 wrapup

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.

The sessions

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:

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:

AODC 2010 wrapup

AODC 2010 wrapup

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:

AODC 2010 wrapup

AODC 2010 wrapup

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:

AODC 2010 wrapup

AODC 2010 wrapup

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!

AODC 2010 day 2: Engaging your readers in the documentation

Last month I attended AODC 2010, the Australasian Online Documentation and Content conference. Over the last few weeks I’ve been posting my summaries of the conference sessions. Now it’s the turn of my own presentation.

My presentation was called “Engaging your readers in the documentation”. Conversation, the social web, community – they’re all the buzz. OK, sounds good, but how do you get your readers involved in the documentation?

Downloading the presentation

Attached to this blog post are two PDF files containing my presentation:

Overview of the presentation

At Atlassian, we’ve been experimenting with social media and other techniques. My presentation takes an in-depth look at the tools and techniques we’re using.

We write and publish our documentation on Confluence wiki. The wiki, and in particular a Confluence macro called the Widget Connector, provide many opportunities for integrating other social media into the documentation pages. Examples of such social tools are Twitter, Flickr and Wufoo.

Even if you’re not using a wiki, you’ll still be able to apply these ideas and techniques in and around your technical documentation.

AODC 2010 day 2: Engaging your readers in the documentation

AODC 2010 day 2: Engaging your readers in the documentation

The presentation covers the following techniques and tools for engaging your readers:

  • Getting feedback from readers via comments on the documentation pages.
  • Using Wufoo forms as another feedback mechanism. You can embed a Wufoo form into your wiki page or other web pages.
  • Holding a doc sprint, where a group of people got together to write tutorials. Our focus was plugin and gadget development, so we invited the developers too. We use a Flickr photo stream in the doc sprint wiki to show the sprinters in action.
  • A few ways of using Twitter‘s hash tags, viral tendencies and 140-character limitation to their best advantage. We tweet our release notes. In one of our long procedural documents, readers can tweet when they hit each milestone and can follow the tweets to see how others are faring. Breaking news: We’re about to start encouraging people to tweet their hints and tips. We’ll embed the Twitter stream into a documentation page, so that tweeters can see their tips appearing in our documentation, and readers can see other people’s hints in real time.
  • Linking to external blog posts from within your documentation. Our “Tips of the Trade” pages link to external blog posts where our readers share their own hard-won tips and techniques.
  • Letting other people edit your documentation. Is it safe? We use wiki permissions to control who can do what. Technical writers monitor all updates via RSS feeds and wiki watches. Our developer documentation is open for editing by any logged-in user. That means that anyone can click the “Sign Up” button, get a wiki user ID and start editing the developer docs immediately. We have a contributor’s licence agreement that we ask people to sign before they get permission to update the product documentation. A Creative Commons (cc-by) licence lets readers and contributors know what copyright rules apply.
  • The idea of documentation as an emotional experience and of having a game in and around the edges of your documents. The presentation looks at a case study, Atlassian’s Here Be Dragons documentation.
  • Lots and lots of links and references in the last few slides. In particular, I’ve linked to some blog posts by other technical writers who are talking about and experimenting with similar techniques.  Anne Gentle’s book is a great source of ideas: Conversation and Community: The Social Web for Documentation. Peg Mulligan wrote about “social business, also known as enterprise 2.0″. Julie Stickler blogged on HeraTech about Agile Doc Reviews – The Documentation Sprint. Lisa Dyer writes “I suppose we’ll soon agree on a name for the era we’ve entered” in her blog post about “Business intelligence, intelligent content and devices, games, and noise”. Bill Kerschbaum asks “Did you hear the one about the user guide with a sense of humor?” Ellis Pratt’s writes on the Cherryleaf blog about “Turning technical documentation into an emotional experience (for the customer)”.

I hope you enjoy the presentation. Let me know if it gives you some useful hints and ideas. :)

AODC Day 3: I can’t spell Ambliance!

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!

AODC Day 3: I can't spell Ambliance!

AODC Day 3: I can't spell Ambliance!

In this presentation, we looked at some horrors that technical writers may encounter and indeed should do our utmost to avoid.

Eggcorns

“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.

Mixed metaphors

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

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ē-ə)

  1. 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. ;)

My conclusion

A fittingly boisterous end to AODC. Fun, but with a serious undertone. Thank you Choco.

AODC Day 3: Help Authoring Tool Comparison

Two weeks ago 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.

Matthew Ellison presented a number of excellent sessions at this conference. His Friday session was called “Help Authoring Tool Comparison”. He discussed what a help authoring tool (HAT) can do for us as technical writers, then did a detailed comparison of a few popular tools.

What a HAT can do for you

HATs hide the complexity and allow you to concentrate on the content. You don’t need to worry about coding and scripting, conditional tags and other mechanics under the hood.

HATs produce some very nice output, such as browser-based help (WebHelp), PDF and many other types. On the whole, HATs produce the tri-pane output format of online help. If that’s what you need, they make it very easy to do.

They provide help-specific features such as context sensitivity, indexing, dropdowns and related topics.

You can also use HATs for single sourcing.

In summary, HATs cater to our specific needs as technical writers.

Things that may count against a HAT

HATs tend to be proprietary and non-standard. For example, a HAT that supports DITA may not use compliant DITA. This may mean you’d find it difficult to migrate to a different tool. It’s a trade-off between the ease of use and the loss of flexibility.

Compared to a full CMS with XML management, HATs offer limited facilities for content re-use and content management.

Examples of HATs

Matthew emphasised that all the HATs he discussed are excellent tools. His presentation covered the following tools, which are the most popular of the HATs available:

  • Adobe RoboHelp (also TCS2, which contains a slightly different version of RoboHelp that offers better integration with FrameMaker)
  • Author-it
  • ComponentOne Doc-To-Help
  • EC Software Help & Manual – a really nice tool.
  • MadCap Flare
  • WebWorks ePublisher – This tool has been around a long time. It’s not an authoring tool, but rather converts content from one format to another.

Matthew gave us a list of the features that almost all HATs have in common. Then he discussed some criteria for selecting a HAT, examining a number of tools and analysing the strengths and weaknesses of each tool. He covered the following aspects of each tool:

  • A short description of the tool
  • Workflow
  • UI and usability
  • Key strengths
  • Key weaknesses
  • The tool’s own help

I didn’t have time to take notes on everything covered in the presentation. Here follow the notes that I did take.

Adobe RoboHelp

RoboHelp stores its content as XHTML. You work on topics, basically one topic per file. RoboHelp publishes to a number of different formats. The output to AIR Help and WebHelp are very good indeed.

I found this point interesting: If you want a printed document, Adobe recommends that you write your documents in Microsoft Word and link them to RoboHelp as the publishing engine. When printing, print the Word document. For other output formats, publish via Robohelp. You can print directly from RoboHelp, but the output is not great.

If you have TCS2 RoboHelp, you can link FrameMaker documents in the same way as Word documents. FrameMaker gives you a much richer print capability.

The RoboHelp UI and usability are good. RoboHelp goes to some pains to retain a Word-like UI (pre-2007 Word). The UI for linking and importing is not so good.

Other notes:

  • You cannot share resources (stylesheets, icons, snippets) across multiple projects.
  • The download file is very large.
  • RoboHelp’s own help is not all that great, chiefly because it contain features that you cannot create from RoboHelp itself. The information is also not very well structured.

Author-it

Author-it stores its content in a single library in the database. You can connect to your own database: SQL Server or JET / SQL Server Express (free). On the minus side, Author-it stores the content in a proprietary rather than a standard storage format.

Author-it offers a very powerful capability for content re-use.

You can publish to a number of different output formats. All print outputs are generated via Microsoft Word. This can be seen as clumsy and a problematic dependency. It does produce excellent Word documents.

The UI is very complex, requiring a steep learning curve. It has a very modern look and feel.

Author-it has a number of capabilities, probably the longest list of all the HATs. Some of the add-ons are very powerful, such as authoring memory which tracks duplicate content. It has good support for localisation. Another feature offers web-based authoring too.

The help system is pretty good, and is recognisably generated from Author-it itself. It’s also mirrored on the web, so you can find the information via Google too.

ComponentOne Doc-To-Help

This is the original HAT. Originally the idea was to work in Word and convert to Doc-To-Help. But now you can also choose to edit in XHTML using the Doc-To-Help WYSIWYG editor.

To create styles, you actually create Word .dot files. At first use, this seems a bit odd. Doc-To-Help generates CSS from the .dot files.

It also has a database where you can store metadata.

Doc-To-Help offers a number of output formats.

The UI has improved over the years. It’s a professional-looking, ribbon-based UI.

Doc-To-Help has some cool features, such as the ability to create relationships between topics, similar to the way Author-it does.

It also integrates with Microsoft Sandcastle for documenting class libraries based on comments in the code.

Doc-To-Help’s own help is good.

EC Software Help & Manual

Help & Manual has a very nice WYSIWYG editor, where you edit in XML. It has its own DTD.

It imports content nicely. If importing from Word, save to RTF first. There’s no FrameMaker or DITA support.

The UI is very nice. Of all the tools, it’s the easiest and most comfortable to use (even though ribbon-based). The UI is driven by the table of contents. It offers a simple user experience, yet there are some good advanced features which you can find if you look for them.

One great advanced feature is the skins that you can use to achieve consistency across projects. You can also share resources, such as style sheets, across projects.

MadCap Flare

All editing in Flare is in XHTML, using the WYSIWYG editor.

Flare does a very good job of producing print and help output formats. There’s also a WebHelp Mobile output

You can input DITA, as well as other formats.

The UI is fairly easy to learn, but has some stumbling blocks. You do need to understand CSS to get the most out of it.

Flare has the most excellent help system Matthew has ever seen.

Offering your users the ability to collaborate on your help pages: As an add-on, you can buy the collaboration module so that users can comment on the topics and read each others’ comments.

WebWorks ePublisher

Note that ePublisher is not an authoring tool. There is no editor. You use it to publish content from Word, FrameMaker or DITA to a large number of output formats.

ePublisher offers a large number of mappings that you use map from your input styles to your output styles.

The UI and usability is slightly confusing. There are actually two products involved. ePublisher Express is very simple. That’s the one you use to publish the output. ePublisher Pro is where you create the mappings, and the UI is more complex.

The WebHelp output is not very pretty or professional. The TOC (table of contents) output is fixed by the TOC of the source document.

ePublisher’s own web-based help, published on a wiki, is just bad. On the other hand, the local help that you get when you install the product is much better.

Final comments from Matthew

Always test drive with real data before buying a tool. All the products discussed in this presentation are great tools!

My conclusion

This was a very thorough and in-depth analysis of the features, strengths and weaknesses of the most popular HATs around. I didn’t have time to take enough notes to do it justice. In particular, Matthew showed a useful workflow diagram for each tool. Thank you Matthew for another great presentation.

AODC Day 3: Introduction to DITA Conditional Publishing

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!

AODC Day 3: Introduction to DITA Conditional Publishing

AODC Day 3: Introduction to DITA Conditional Publishing

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

Example:

<step audience="advanced">

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!

My conclusion

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.

Update on DITA Features, Tools and Best Practices

Follow

Get every new post delivered to your Inbox.

Join 1,388 other followers

%d bloggers like this: