Category Archives: AODC

AODC 2010: Uncle Dave’s Trivia Night

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

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's 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:

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

Of course, the winning team gains the privilege of having their name engraved on the trophy for all eternity:

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

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):

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

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

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

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:

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

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:

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

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:

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

Wanna know what we won? A coaster, a pen and a sweet. The sweet was an afterthought:

AODC 2010: Uncle Dave's Trivia Night

AODC 2010: Uncle Dave's Trivia Night

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.

Uncle Dave’s Trivia Night was an experience to be remembered. Thanks to Tony and Dave and all the AODC triviaphiles.

AODC Day 3: Converting to Structured Content

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 Dr Alan Burton, the presenter. Any mistakes or omissions are my own.

The first session on Friday was titled “Converting to Structured Content”, by Dr Alan Burton. Introducing his talk,  Alan showed us some “scary” pictures of the world he lives in. Scary indeed — a wall of codes. With a charming smile, he admits to being a “hardcore geek”. From the moment Alan starts speaking, we see that he has a good dose of the AODC sense of humour. 🙂

AODC Day 3: Converting to Structured Content

AODC Day 3: Converting to Structured Content

The problem that Alan’s talk addressed is this: You’re told that you need to move your content to XML. You have loads and loads of unstructured content. It’s in FrameMaker, Word, other desktop publish applications, or even more fun: it’s on paper.

Who does the conversion?

Alan discussed various options to consider when deciding who will convert the documents to a structured format:

  • You can do it yourself, if you have the technical knowledge required.
  • The company’s IT department could do it. Alan jokingly referred to the “IT Crowd” — are you happy for Moss to do your conversion? 😉
  • You can outsource it to someone like Alan. (He acknowledges with another disarming smile that there’s no-one quite like him.)
  • If you consider outsourcing the work to an overseas company, take into account that this can lead to difficulties when communicating requirements.


You need a sample of the documentation that’s to be converted. What’s more, it must be a representative sample. For example, check whether the documentation as a whole contains tables, images, special characters, mathematical symbols. If so, are they represented in the sample? For best results, you need to be given the full documentation set in the analysis phase.

Find out whether the documents comply to a template. If the answer is yes, ask how long the documentation has been around and how many authors have had a hand in it. What are the chances that it really does comply to the template?

Here’s Alan’s recommendation, assuming your source documents are in Word: Convert all the Word documents to RTF and then feed them through an analysis tool. He extracts a complete list of all styles that appear in the documents. If there is a large number of styles, you may have a problem. He is building a set of utilities that let him look at styles, special characters, symbols etc within the documents, without himself having to read each and every document. In this way, he builds up a picture of how easy or difficult it will be to convert the document.

Ask questions such as: “I see that you use italics to represent words that appear in the glossary. Do you use italics for any other purpose, such as titles or Latin words?”

Do the analysis before you choose or create your DTD, and before you buy any software.

Document the results of your analysis in detail.


After the analysis phase, you know what you have, but you still need to find out what you actually want. Things to consider:

  • Metadata
  • Indexing for search
  • Online and/or paper output
  • Cross-referencing

Markup specification

Alan creates a “markup specification”, which is a detailed requirement specification for the conversion. You need to add examples for each requirement.  This documentation provides the input into the design of your DTD.

Mapping document

Alan creates a document that maps the styles of the source document to the XML elements and attributes.  The developers will use this document to create or customise the software that does the conversion.

Checking the results of the conversion

When you receive the converted documentation, you need to check it to see if it’s actually what you want.

These are some of the problem areas that Alan mentioned:

  • Tables
  • Graphics — format, naming conventions, storage
  • Cross-references
  • Metadata
  • Forms — these are very hard to recreate in XML
  • Mathematic and scientific symbols and formulae

FrameMaker has a Migration Guide that tells you how to convert from unstructured FrameMaker to structured FrameMaker content. This is a useful tool. You can then export to XML. You do need to do some cleanup afterwards, either manually or with scripting.

You could convert from Word to FrameMaker, then to Structured FrameMaker.

Converting from Word to XML, you usually convert from Word to RTF and then to XML. Alan has done this once, in a very controlled environment and with just one document. It can become fairly complicated.

Converting to DITA is very challenging. You will probably need to split input files into different output files. It is unlikely that you can automate the insertion of metadata. You may need to rename graphics and create multiple graphics formats.

Bottom line

You will never end up with a clean result immediately, no matter what any tool may claim. You will always need to do some manual cleanup, and you will probably need to get a programmer to do some scripting.

My conclusion

This was a good, fast-paced walk through some scenarios and guidelines for converting from unstructured to structured content. I could tell that Alan has a lot more information to share. Thank you for a great session, Alan.

AODC day 2: Optimising your Content for Google Search

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 Joe Welinske, the presenter. Any mistakes or omissions are my own.

Joe Welinske presented the last session on Thursday, titled “Optimising the Googleability of Your Content”. The subject was search engine optimisation (SEO). Joe is really excited about this topic. He thinks it’s one of the most important skills for a user assistance expert to acquire. Potentially, it also offers a good opportunity for consultancy.

SEO is complex, but we need to learn about it. Joe calls it “embracing the beast”: If people are going to be using Google, then we want our material to come out at the top of the search results.

These are the topics he covered:

  • Get all your content on a public-facing server.
  • Learn about Google Search.
  • Learn about SEO (search engine optimisation).
  • Find out how to use other search engines.
  • Create a custom Google Search for your UA (user assistance) material.

Getting your content onto a public-facing server

This is the single most important thing that has to happen: Your content has to be on a public-facing server.

There are ways to mirror your internal content onto public-facing servers. Joe talked about a few of them. Ultimately, the best way may be to migrate all content to web-based standards.

Security issues when publishing content on the web

Many organisations keep their content behind the firewall, or have privileged content requiring login. Security is a very real concern. Moving to a public-facing server may be a big change for traditional content developers, and a challenge for organisations that have up to now kept their documentation hidden from public view.

Organisations need to take a detailed look at all the help components they provide and see what can and what can’t be published on a public-facing server.

We should be aware that our users are using Google anyway, and we should ask ourselves what these users find when they do a Google search for information on our products.

We could put together examples of Google searches, to show management what people will be finding, given that they can’t find our own documentation. For sure, people will be posting information about your systems to answer other people’s questions.

Google search indexing

Note that some content will not index effectively. Joe gave some tips on the type of content that Google can index well and the type that may cause problems.

Good candidates for Google indexing:

  • Web sites.
  • Web-based help, such as output generated from Flare or RoboHelp. Note that frames may make the content less favourable for indexing. Google has a hard time making sense of content in frames.
  • Eclipse Help is a good candidate, because it’s XHTML.
  • PDF is good, because Google has put effort into indexing it. Some PDF formats may be less effective.

What does not work well:

  • Microsoft Help (CHM and HLP) — This format has some HTML but is mostly locally-installed and uses a lot of proprietary code.
  • Apple Help, Oracle Help for Java and JavaHelp.
  • Flash — Google has done some work to be able to index text in Flash files, but images and videos not.
  • Almost any proprietary markup — Google has problems interpreting it.

Bottom line: The more open standards you use, the better off you will be.

What about loss of context?

When we put together online help systems and context-sensitive help, we have control over the path the user follows. But when the user comes in via Google search, we don’t have that control.

Some tips from Joe:

  • Provide navigation elements on all pages.
  • Add branding, so that people know that they have found your site and thus the official documentation.
  • Include the date last updated and the version of the application that the help covers.

Examples of SEO

Joe showed an example of a Google search he entered. He asked how to print a calendar in Excel. The first result returned was a link to Microsoft Office Online, telling you how to print a blank calendar. This was exactly what Joe wanted to do. What’s more, the content was an exact copy of what’s in the HTML Help provided with Excel, but laid out differently. So Microsoft has their SEO sorted out, and they are mirroring local help content in the web-based help.

Similarly, he entered a Google search for printing a Google calendar. Again, the Google web-based help was right at the top of the results. Google provides only web-based content, so they don’t need to support mirroring of content.

In contrast, when you search for “print an ical calendar”, there’s nothing near the top from Apple. So Apple needs to work on there SEO in this particular context.

How Google search works

It’s a combination of brute force and extremely clever technology:

  • Brute force: Google runs a gigantic server farm in Washington, that buys electric power directly from the hydroelectric dam nearby.
  • Extreme smarts for indexing information: Google has clever and secret algorithms for ranking content.

How does the ranking work?

Joe mentioned the following factors that influence the ranking of search results:

  • Fresh and real content — The search index recognises a page as offering a solid body of information, not just fake content. This is an area we technical writers excel at. Link farms out there put together random text and try to fool Google. But our standard documentation will match up as high quality.
  • Nomenclature — We use the right terms and the right labels in our documentation. If people use these terms in their searches, our content will quickly match.
  • Links pointing to our content — In Google’s eyes, links indicate what other people think of the information on the page. When many people link to pages, this makes it more likely in Google’s eyes that this is well-respected content.
  • Google Ads — There is some indication that your pages will be better indexed if they contain Google Ads.

Joe gave us these sources as guidelines on optimising your content for search:

Joe had a number of more in-depth hints on things like:

  • Including the “robot.txt” and “sitemap.xml” files.
  • Registering your site at “”. (It’s free.)
  • Including metadata such as title, description and keywords.
  • And more. I’m sure Joe would be delighted to pass on this information if you contact him.

A tool to help analyse your pages for SEO

Of huge benefit is a tool called Go Daddy Search Engine Visibility. It goes through your pages and finds any search engine deficiencies. There are other tools that do the same thing.

Other search engines

Joe touched on other search engines, such as Yahoo and Bing. These are also important. Each has a separate registration procedure.

Getting other people to link to your site

Send people links to your content, such as sending links via email. Submit links to relevant sites. It’s a tough process and there’s no easy way to do it.

You can also think about community building:

  • Start a LinkedIn group.
  • Add YouTube videos with links in the metadata.
  • Add a Facebook fan page.
  • Tweet links via Twitter.
  • Encourage bloggers.
  • Supply RSS feeds.
  • Consider translated content, such as having even just a single page about your documentation, in different languages. Google indexes different languages too. Also, people who speak that language will at least learn about your documentation and your product. They can then click through to read the information in English.

Creating a Google custom search

It’s easy and free to register to create a custom Google search. Register your site. Google supplies you with the code you can use to put the search box onto your site. Google will index your site for you. Your search box will bring up results for your site only.

My conclusion

This was intensely interesting and full of information. I could not hope to capture everything that Joe told us. Thank you Joe! This presentation gave me a lot to think about and experiment with.

AODC day 2: What Kind of Assistance do Users Really Need?

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.

AODC day 2: What Kind of Assistance do Users Really Need?

AODC day 2: What Kind of Assistance do Users Really Need?

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.

Video tutorials

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)
  • Response
  • Identity

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.

My conclusions

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.

AODC day 2: A Beginner’s Introduction to DITA

This week I’m at AODC 2010, the Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. In this session, though, we’re dealing with wolves, not crocodiles. 😉 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 Suchi Govindarajan, the presenter. All the mistakes and omissions are my own.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Suchi Govindarajan had a catchy title for her talk: “Who’s Afraid of the DITA Wolf?”

At the beginning of the session, Tony Self handed out some pretty coloured squares of paper to each of us. Intriguing! The coloured paper was soon explained. Suchi started by telling us a story about origami. Of course, this set me wondering what this origami had to do with DITA! Good start.

Suchi said that she found it really amusing that she was here talking about DITA. About a year ago, she was totally baffled about DITA. Then she attended a course given by Tony Self. Now she’s here to give a beginner’s view of DITA.

She led us through the steps to make an origami pelican, following the step-by-step instructions in her slide show. I’m hopeless at things like origami, but nevertheless I managed to follow the steps (with help from my neighbour) and make something resembling a bird.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Next, Suchi showed us some text about origami: an explanation of the theory of origami, an investigation of the maths behind origami, and other theoretical scripts about origami. She explained how different texts have different purposes, and not all are step by step guides, and not all are useful to a beginner.

DITA introductory material

What did Suchi’s origami demonstration have to do with DITA? She showed us some introductory material to DITA, pointing out how the texts were full of words and terms that a beginner would not understand.

So Suchi has written her own definition of DITA, specifically for beginners:

DITA is a standard for technical documents that’s designed to be used with XML. It comes with some free publishing tools.

We already know DITA

As technical writers, we already know much about DITA. Suchi showed us how a number of the concerns DITA addresses, and many of the terms used, have been part of standard technical writing for years. Examples are content re-use, topic-based authoring and content models.

DITA has an elegant way of handling these standard technical writing concepts.

How to learn DITA

Before you start, you need only a very little:

  • An understanding of XML elements and attributes — just know what they are.
  • An idea of the three DITA topic types: concept, task and reference.

Then get a DITA editor, such as XMLMind or XMetal. Suchi usees and recommends XMLMind. You can download a free edition for personal use.

From that point on, the editor helps you to learn the quirks of DITA. Suchi gave us a quick demo of XMLMind, showing us how the editor enforces the DITA rules while you are writing your content.

At this point, you don’t need to know about the complex features of DITA like specialisation, customisation, inheritance, etc. You also don’t need to know about the DITA “topic” topic.

You also don’t need to know about XML rules, validation and well-formedness. The editor will take care of that. You can learn about it later, once you’ve got through the beginner stage.

Because DITA tags are semantic, it’s easy to guess what each element means judging by its name.

Start with a good example. Download and analyse some sample topics. Suchi gave us a link to the DITA OT user guide as a good set of sample topics.

She also recommends this tutorial: DITA for Solo Writers, the Lone-DITA guide.

The real wolves of DITA

DITA is not a wolf, says Suchi. 🙂 On the other hand, the DITA OpenToolkit is horrible. Don’t use it!

Another wolf is ourselves. If you start with a closed mind, it’s hard to learn what DITA offers.

Going further

Once you’ve done some editing and created some content, you can start looking at publishing your DITA content. Here’s where you would install the DITA OpenToolkit, but don’t use it. Instead, install one of the other tools that use the toolkit:

  • WinANT
  • XMLMind DITA Converter
  • Other publishing tools you already own

My conclusion

Thank you to Suchi for a calm, reassuring introduction to DITA. Suchi had the audience in the palm of her hand. Her speaking style is relaxed and charming. She told us about a one-day DITA workshop called “DITA in a Day”, that she has created. It sounds well worth attending!

%d bloggers like this: