AODC – separating content, structure, format and behaviour

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😉

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 16 May 2008, in AODC, technical writing, xml and tagged , , , , . Bookmark the permalink. 5 Comments.

  1. It all sounds very nice, and in fact I have a website I made for a client that is using exactly this. But given the choice I would dump XSLT for anything simpler anyday. XSLT is just very hard to maintain, it’s a functional programming language and written in XML — it requires a special mindset to use. And it’s quite a hell to maintain several years down the road.

    Jett Atwood wrote a blog post on this recently, http://www.codinghorror.com/blog/archives/001114.html
    I completely agree with him — XML is most probably not suitable for what XSLT is trying to do.

  2. It sounds like Docbook, which is the de-facto documentation standard in the open source world. There’s also Apache Forrest (http://forrest.apache.org/), which has a simpler XML vocabulary.

    This works fine for technical people, but I’ve found that technical writers have an aversion to XML. Where I work the tech writers have been campaigning to convert some nice clean Forrest docs into a content-and-presentation-mixing Wiki system😉

  3. Interesting comments from Evgeny and Jeff, both experienced in the use of XML and XSLT.

    Evgeny, speaking as a technical writer, I find it very interesting to hear from someone who has had experience maintaining the XSLT down the track. Technical writers don’t have much time to play with technology, as we’re focused on producing the content and lots of it. I’ve played with XSLT, but never in a production environment. It seems to be a technology that demands a lot of discipline and organisation from the author. Put this into a multi-author environment and spread the time frame over a few months or years, and things can fall apart quite quickly.

    Jeff, funny that, where I work the technical writers are also lobbying to move some Forrest docs into a wiki😉 The main reasons are that the XML coding demands a lot of time, and is fairly specialised. It requires a skill different from all the other docs we maintain. Also, it currently generates a basic HTML-based output which goes onto a web site — no opportunity for the users to comment or contribute.

    Wouldn’t it be cool if the wiki stored its content in an accessible XML format, with stylesheets, JavaScript and transformation separated into other accessible bits too. Then the technical writers can work away on what they do best (organisation of information), other gurus can look after the presentation, structure and behaviour of the wiki page, and the wiki content can be automatically output into other formats and media at the drop of an XSLT hat🙂

  4. This concept does work, depending on how and what you use it for. Having worked in a multi-national legal publishing firm, I can say this help saves the production staff a lot of time and effort in producing text that complies with the house-style or the style required by the publication. Mapping XML content for style for typesetter is great fun, and I would do it all over again!

  1. Pingback: one man writes » Recently Read

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: