Digression on Documentation: DITA

As is the way of things, I’ve been diverted from the delights of VBA, on to some other work. This is a migration of the system definition documentation for a major financial system, from traditional Word documents to an XML-based architecture called DITA. (Somewhat fancifully, the ‘D’ stands for Darwin, which is appropriate in this, his bicentenary year).

The production of technical documentation is undergoing something of a revolution at present. This is due to the maturing of a raft of technologies based on the XML markup language. Broadly speaking, these technologies provide a solution that sits between monolithic documents-as-files (such as Word documents), and relational databases, as complex aggregations of fine-grained information records.

With a Word document, the unit of content is the same as the unit of presentation: a file is edited, and the same file is printed. This applies equally to web pages (HTML), but with the page as the unit. In practice, it is difficult and time-consuming to identify, extract and recombine fragments of documents to produce new deliverables.

With a relational database, the information records can be conjoined, aggregated and filtered in very complex ways, using a query language (SQL). However, databases are not really suited to holding large free-text elements, like a section of a document. Also, there is no notion of hierarchical structuring in query output, in contrast to the hierarchy of chapters, sections and sub-sections that we are familiar with in documents.

The XML-based solutions aim to provide a middle course. Content is created and held in a form that is structured enough to identify, extract and recombine fragments of documents to produce new deliverables. At the same time, the content does not carry information about presentation (either the target format or the details of layout). This is provided by transformations of the content to produce deliverables in different formats, such as Word or PDF for printable documents, or hypertext (XHTML) for web presentation or online Help.

The challenge is to come up with an information model that defines and relates appropriate topics (i.e. basic chunks), in ways that allow querying, selection and combination in flexible ways. There’s a trade-off here between flexibility and chunk size. Too fine-grained and it’s impossible to manage; too coarse-grained and you’re back with monolithic documents. There’s a wider trend towards ‘medium-sized’ information chunks: think of blog posts, like this one, or Wiki pages.

More on this anon…


14 Responses to “Digression on Documentation: DITA”

  1. 1 make up tips blog March 19, 2013 at 9:57 pm

    I appreciate your wordpress template, where
    do you down load it through?
    Your website doesn’t display appropriately on my iphone4 – you might wanna try and fix that
    Music began playing anytime I opened this webpage, so frustrating!
    I believe one of your commercials triggered my web browser to resize, you might want to put that on your blacklist.
    I just added this blog site to my feed reader, excellent stuff. Can not get enough!
    This is a terrific blog, will you be interested in doing an interview about just how you created it? If so e-mail me!
    Thank you, I have recently been hunting for info about this topic for ages and yours is the best I have discovered so far.

  2. 2 Winnie April 18, 2013 at 10:23 am

    I simply hoped to just take a few moments and inform you that I enjoyed
    the blog post. I in all honesty don’t believe many people know the amount of labor that goes into constructing a good post. I am sure that this will be sort of random but it really bothers me sometimes. Nonetheless outstanding website.

  3. 3 free pub quiz answers May 7, 2013 at 1:13 am

    On Sunday nights Erin Jaimes hosts a blues jam where anyone from Alan
    Haynes to Gary Clark, Jr. Anna had been looking through my phone while I was naked.
    The decline of the East side blues scene was disheartening, but, it also gave rise to the need for a
    fresh start, which came in the form of the next blues-only venue, Antone’s, founded by the late Clifford Antone, during the summer of 1975.

  4. 4 Marissa May 30, 2013 at 2:29 am

    Hello great website! Does running a blog such as this take a massive
    amount work? I have no expertise in programming but I had been hoping to start
    my own blog soon. Anyway, should you have any suggestions or tips for new blog owners please share.
    I know this is off topic however I just wanted to ask. Appreciate it!

  5. 5 why i cant get pregnant August 15, 2013 at 10:47 pm

    Thanks for the auspicious writeup. It if truth be told was a leisure
    account it. Glance complex to far introduced agreeable from you!
    However, how could we keep in touch?

  6. 6 Free Microsoft Points Codes List June 13, 2014 at 3:31 pm

    Hello! Quick question that’s entirely off topic.
    Do you know how to make your site mobile friendly?
    My web site looks weird when browsing from my iphone 4.
    I’m trying to find a template or plugin that might be able
    to fix this problem. If you have any suggestions, please share.

  7. 7 LAN WAN July 3, 2014 at 11:38 am

    Hi there colleagues, its great article regarding educationand completely defined, keep it
    up all the time.

  8. 8 women health 2014 August 17, 2014 at 1:01 pm

    Furthermore, this particular process assists folks to attain their end
    targets. Despite being one of the most common health afflictions around today, being overweight
    does not have to be a permanent condition. Are you now being told that the healthy diet isn’t a
    good idea and now you have to eat vast quantities of cake in order to lose weight.

  9. 9 Blanca September 27, 2014 at 11:53 am

    If you base your decision solely on price, then you’ll end up dissatisfied with the quality of schooling.
    Many of America’s best colleges and universities have
    been established for around 100 years. It’s crucial that you come ready to focus on specially why you deserve a promotion if you think that you do.

  1. 1 Adding HTML Help « Roy MacLean’s VBA Blog Trackback on October 21, 2009 at 2:13 pm
  2. 2 Sub-sequence Cursor « Roy MacLean's VBA Blog Trackback on May 20, 2010 at 8:35 am
  3. 3 Spreadsheets in XML « Roy MacLean's VBA Blog Trackback on November 1, 2010 at 12:08 pm
  4. 4 Still here… « Roy MacLean's VBA Blog Trackback on March 5, 2011 at 6:07 pm
  5. 5 Spreadsheets in XML | Server Twenty-Seven Trackback on April 17, 2012 at 7:21 pm

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 )

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

August 2009
« Jul   Sep »

%d bloggers like this: