Thoughts and Notes Ideas that stay with me long enough to get written down

DITA – The Things Experts Say I am Doing Wrong

A few months ago, JoAnn Hackos told me that I'm not really using DITA.  Yesterday, Eliot Kimber told me I'm not really doing reuse.

In a way, it's an affirmation for me to have disagreements with such knowledgeable, skillful people and to honestly believe that I'm right.

We use generic DITA topics.  JoAnn's point is that without using specializations of the  generic topic in DITA we are not taking advantage of  DITA.  We're just writing XML.  In a way, I agree.  One of the great things about using specialized topics is that you can easily create and enforce a consistent information model.  However (you knew that was coming, right?), DITA is much more than an information model. You can create information models using many different architectures or processes.  It's quite possible to create and enforce an information model using plain text files.  Besides, taking JoAnn's position to it's logical extreme, how can you say you are really using DITA if you haven't specialized everything?  Why is a task topic specific enough?  Shouldn't every project have a task topic that is designed for its information model?  If that's a requirement to really be using DITA, then nobody is really using DITA.

At the CMS/DITA conference, Eliot asked if anyone using DITA 1.1 was reusing content.  I, and others, raised our hands.  He then made the statement that we were wrong - no one using DITA 1.1 is doing reuse.  It was a typical Kimberism.  Broad, strong statements made, partially, to make his audience think about reuse.  When questioned about it, he clarified by saying that "unbounded reuse is not possible in DITA 1.1," which, I think, nearly everyone would agree with.  However, bounded reuse is possible.  For example, in our system all of our content is stored in
one repository.  All the content is always available to every project at build time.  As an author of the API documentation, I can always depend on the content from the online help.  That means conrefs are always valid.  It gets more tricky when you start using cross-references, either using the xref element or a reltable.  The problem is that while I can be sure the content that is being linked to is available at build time, I cannot be sure that the content is available in the target.  To use an example, I cannot guarrentee that "About Accounts," a help topic, is going to be in the PDF version of the API, so any content in the API guide that includes a link to "About Accounts" will break.  So what, you say, "As the API writer I won't put in one of those links."

Ah, but what if you are reusing content and that content includes a reference to "About Accounts"?  If it does, your guide has a broken link.  Here's the bad part - you cannot know that the content you reuse doesn't include that link.  The way to resolve that, as Eliot hinted at, is to bound your reuse.  You need to either ensure that elements with cross-references are not reused, or you need to test for broken links at build time.  We do the latter.

If a link in the PDF fails, we drop it.  The text is still there, but the link is gone.  The writer gets a message from the build indicating the issue, and then it's the writer's choice to either drop the reuse, change the source with the cross-reference, or let the build drop the link.

In a way I like the problem.  I have two reasons for that.

Our main focus is online content delivery.  When your online project includes search and hierarchical navigation tools (like a table of contents, index, etc.), inline links are, IMO, a usability problem rather than a usability enhancement.  First, due to the fact that we need to style a link differently than non-link text, when a user scans the content, the link jumps out.  The user focuses on it.  That leads to the second problem; a treasure hunt.  The user scans the page, finds a link, clicks it, scans that page, sees a link, clicks it, etc. Next thing you know, they have scanned 10 different topics, the answer to their question wasn't as apparent as all the links, and so, the user gets frustrated; "I looked all over the doc and I couldn't find an answer".  So, inline xrefs actually make the documentation less effective.

The second reason is a more subtle one.  A topic is the smallest piece of information that can stand on its own.  If you include an xref, is it really standing on its own?  It's a crutch that lets the writer be lazy.  If they need the information in the link to really grok the information in the topic, then the topic doesn't stand alone.  If the topic works without the link, then why include it?  You don't know what the user is trying to do, and trying to predict it with an inline link muddies the path the user would choose to follow.

Testing IE – Virtual PC

Okay, I've complained a lot about Internet Explorer.  With good reason, in some cases, sometimes just because I'm complaining.

One of the things that has always bugged me about IE - you can only have one version on your computer.  That makes it tough to test versions 6, 7, and 8 without having multiple computers.

Microsoft stepped up and created virtual machine images for each variable.  See IE6 and IE7 Running on a Single Machine.

Do I want to be using multiple VMs to test a browser?  No, but at least now I can do it.

Using EXSLT date-time functions in Saxon 6.5.5

I needed to put a time-stamp in a file I was generating with XSLT and Saxon. Saxon supports parts of EXSLT, and one of the parts supported is @date:date-time@. It's kind of challenging to figure out exactly how to make it work, though, at least it was for me. In hopes that I'll save someone else some work, here's how to add a time-stamp using Saxon 6.5.5.

<?xml version="1.0" encoding="UTF-8"?>
<xsl :stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:saxon="http://icl.com/saxon"
xmlns:exsl="http://exslt.org/common"
xmlns:date="http://exslt.org/dates-and-times"
xmlns:func="http://exslt.org/functions"
extension-element-prefixes="saxon exsl date func">
<xsl:template match="/">
Date-time: <xsl :value-of select="date:date-time()"/>
Date-year: <xsl :value-of select="date:year()"/>
Date-month-in-year: <xsl :value-of select="date:month-in-year()"/>
</xsl:template>
</xsl>

I hope that helps someone.

oXygen and profiling

I ran into a little bit of a problem profiling a XSL transformation in oXygen today. Any errors at all in the transformation will cause the profiling to return no value. So, just as a note, make sure your transform doesn't return any errors, not even errors related to being unable to open files using the document function.