ffeathers — a technical writer’s blog

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. With his inimitable flair and style, Dave Gash presented a session this morning entitled “The Search for the UA Grail: True Separation of Content, Structure, Format and Behaviour”.

Dave is the owner of HyperTrain dot Com, specialising in training and consulting for hypertext developers. Today he told us what’s wrong with the way we traditionally do things, what’s wrong with the conventional wisdom on how we might improve our way of working, and what’s a better way.

What’s wrong with the traditional way we do things

The basic problem is that we write our content, e.g. a web page, and tweak elements of it on the fly. For example, we might make some text bold, or colour other text, or whatever. The result is spaghetti code — difficult to maintain and share.

What’s wrong with the conventional wisdom on improving the above situation

People usually say we should “separate format from content”. But what is “format”? That term is too vague. And the phrase implies that everything that’s not “content” is “format”. Wrong.

The better way

We should separate our document into four components instead of two:

• Content (which you might realise via XML)
• Structure (XSLT)
• Format (CSS)
• Behaviour (JavaScript)

What we’re aiming for:

• Maintainability — you can change one of the above four components without breaking the others.
• Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
• Separation of skill sets — different people can work on the component they know best and enjoy most.
• Simplified updating of content — content is likely to be the component you update most often.

How to do it

Dave demonstrated the procedure we would follow in order to separate a document into the above four components. There are five basic steps. Dave walked us through the details of each step, using code examples of CSS, JavaScript, XML and XSLT. In summary, the steps are:

1. Identify all JavaScript and move it to an external JS file.
2. Identify JavaScript that could be better done in CSS. Examples are “onmouseover” and “onmouseout” event handlers that change the style of the text item, and image swaps. Use the CSS “hover” pseudo-class instead.
   • Dave’s tip: You don’t have to specifically code the “I’m through hovering” handler because it’s implicit in the pseudo-class.
3. Move all CSS styles to an external file. Convert local formatting to classes too.

   Dave’s tip: If the boss says “Change the list spacing in all lists on all pages”, it’s in one spot — change it and take the rest of the day off.

4. Add semantic markup to the content, using XML.
5. Now it’s time for some XSLT. Identify the output HTML you want, then write the XSL transforms to produce it.
   • Write small, individual templates to create the HTML for each specific XML tag. Then use the “magic” <xsl:apply-templates/> element to pull it all together. This nests the processing of the templates, so that the transforms will just keep happening for each XML element, hierarchically down and back up the tree, until they’re all done.

The XSLT generates the HTML and links in the CSS and JavaScript.

Dave has made the code available on the “Downloads” tab of the HyperTrain dot Com web site.

A recommended editing tool: EditPlus.

Thank you for a great session, Dave. And a special thanks for changing “behavior” to “behaviour” throughout your presentation, just so that we Ozzies felt comfortable

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. Today’s first session was a short talk by Matt Armstrong about something called “authoring memory”. Have you ever heard of that? I hadn’t.

Matt is the Asia Pacific sales director at Author-it. He started his session by giving us some background about content re-use, why we’d want to do it, the demands we might make of a content mangement solution to support content re-use and the high-level steps we would take to identify content for re-use.

One of the questions he asked us was: Of the people who are already re-using content, how many have a way of quantifying the gains you’ve made by employing content re-use? Surprisingly, the answer was none.

Translation memory and authoring memory

Towards the end of his talk, Matt gave us a tantalising glimpse into what “authoring memory” is. To find out more, we can take a look at the Author-it product, which supports “authoring memory”.

Matt said that translators use “translation memory”. This is a toolset which allows translators to pool their translations into a central database, and then draw from the database when they have similar content for translation. You can match your content with translations made by others all over the world.

Now compare the concept of “authoring memory”. The idea is that a team can build their content in a database. When you are writing a new piece of content, the tool will suggest something that someone else has already written. The content can be shared across the world. You can decide on the spot whether to re-use the bit of content that the tool is offering you.

Matt mentioned these requirements for such a tool — it must:

• Offer you the suggested text and allow you to decide whether to re-use it or not.
• Be fast and immediate.
• Be integrated into your authoring tool.
• Support security and permissions.
• Provide tools for measuring how much content has been re-used and how much time this has saved.

My conclusions

This was an interesting session for me, because it introduced a new concept. Thank you Matt One thing I might suggest, is that the session could have focused sooner on that concept itself, i.e. “authoring memory”. The session had a rather long introduction (from my viewpoint) which covered things that had already been dealt with at earlier sessions in the conference. A demo would have been very useful too.

Here’s a link I’ve found to the relevant page on the Author-it web site. At the conference, of course, we can talk to Matt and see a demonstration of this functionality outside the lecture room.