DITA Specialization Tutorial Now on Xiruss.org
I have started writing a more complete DITA specialization tutorial, which will eventually cover all aspects of DITA specialization and likely lead to additional tutorials on other aspects of using DITA (using the DITA Open Toolkit, writing a Toolkit plug-in, etc.).
The tutorial itself is published on my xiruss.org site here: http://www.xiruss.org/tutorials/dita-specialization/, including a package with all the source materials as well as the generated HTML version.
The source materials are managed for development in the XIRUSS Subversion repository here: http://xiruss-t.svn.sourceforge.net/viewvc/xiruss-t/specialization_tutorial/ should you for some reason want to track the development of the files or get the very latest stuff (can't imagine why but who knows?) or just get a particular file without downloading the whole package.
The tutorial includes an improved version of the DITA attribute domain specialization tutorial I posted here a while back.
It is of course written as a set of DITA topics, which is interesting in and of itself because a tutorial is a type of document for which the DITA concept/task/reference and highly fragmented presentation paradigms are not necessarily a good match. For example, I discovered that the only way to get prev/next links from one topic to the next within a logical narrative sequence of topics is to set their parent container in the organizing map to "sequence". However, this has the effect of numbering each topic in the sequence, which makes sense for the topics that represent a logical sequence of steps within the tutorial, but not for the purely conceptual overview of what DITA specialization is. (This is what the DITA Open Toolkit does today--whether this behavior is required by the DITA spec is a more subtle question.)
So it raises some issues, like do we need a tutorial-specific set of specializations and corresponding rendering customizations to get the effects I want as a tutorial author, or does the DITA spec need to be refined to reflect these sorts of more subtle rhetorical distinctions? Are my topics that describe a sequence of steps to be performed really task or concept topics (I've coded them as concepts because even in DITA 1.1, the task topic type is too restrictive in the way it represents sequences of steps)?
This makes the activity more fun than it would otherwise be--I always like it when the things I do result in both concrete products (a useful tutorial) and help to advance the state of our understanding and, hopefully, the supporting infrastructure, in this case, by serving as an experiment in applying DITA to a type of information for which it was not directly designed (not that I'm the first to create tutorials in DITA, or even the first to think about it--see discussion around this on the DITA Users Yahoo group--but as an informal, spare-time activity, this tutorial provides more opportunity for both introspection about the process and methods and, because it's public, more opportunity for community involvement).
I've also learned a lot about using DITA and hacking the Toolkit and stuff, which makes it fun.
Now if I could just stop waking up at 5:30 a.m. to work on the thing (It's not that I want to wake up at 5:30, it's just that once I am awake and my brain starts spinning I can't go back to sleep, so I am compelled to start working. Good for productivity, bad for physical and mental health.)
The tutorial itself is published on my xiruss.org site here: http://www.xiruss.org/tutorials/dita-specialization/, including a package with all the source materials as well as the generated HTML version.
The source materials are managed for development in the XIRUSS Subversion repository here: http://xiruss-t.svn.sourceforge.net/viewvc/xiruss-t/specialization_tutorial/ should you for some reason want to track the development of the files or get the very latest stuff (can't imagine why but who knows?) or just get a particular file without downloading the whole package.
The tutorial includes an improved version of the DITA attribute domain specialization tutorial I posted here a while back.
It is of course written as a set of DITA topics, which is interesting in and of itself because a tutorial is a type of document for which the DITA concept/task/reference and highly fragmented presentation paradigms are not necessarily a good match. For example, I discovered that the only way to get prev/next links from one topic to the next within a logical narrative sequence of topics is to set their parent container in the organizing map to "sequence". However, this has the effect of numbering each topic in the sequence, which makes sense for the topics that represent a logical sequence of steps within the tutorial, but not for the purely conceptual overview of what DITA specialization is. (This is what the DITA Open Toolkit does today--whether this behavior is required by the DITA spec is a more subtle question.)
So it raises some issues, like do we need a tutorial-specific set of specializations and corresponding rendering customizations to get the effects I want as a tutorial author, or does the DITA spec need to be refined to reflect these sorts of more subtle rhetorical distinctions? Are my topics that describe a sequence of steps to be performed really task or concept topics (I've coded them as concepts because even in DITA 1.1, the task topic type is too restrictive in the way it represents sequences of steps)?
This makes the activity more fun than it would otherwise be--I always like it when the things I do result in both concrete products (a useful tutorial) and help to advance the state of our understanding and, hopefully, the supporting infrastructure, in this case, by serving as an experiment in applying DITA to a type of information for which it was not directly designed (not that I'm the first to create tutorials in DITA, or even the first to think about it--see discussion around this on the DITA Users Yahoo group--but as an informal, spare-time activity, this tutorial provides more opportunity for both introspection about the process and methods and, because it's public, more opportunity for community involvement).
I've also learned a lot about using DITA and hacking the Toolkit and stuff, which makes it fun.
Now if I could just stop waking up at 5:30 a.m. to work on the thing (It's not that I want to wake up at 5:30, it's just that once I am awake and my brain starts spinning I can't go back to sleep, so I am compelled to start working. Good for productivity, bad for physical and mental health.)
posted by Eliot Kimber at 10:07 AM
2 Comments:
Hi,
I am curious. How is the task topic type is too restrictive? You mentioned it is restrictive "in the way it represents sequences of steps". I'm not sure what you mean here? Can you elaborate? I've heard that authoring in DITA topic types in general is restrictive, but can not find specific info to back this up.
I'm looking into DITA for my boss, can you provide more details to your comment so I can investigate more?
Thanks!!!
-p
In DITA 1.1, the Task topic type requires, for example, that you have a <steps> element, which means you can't have a semantic task that just describes the task without explicitly enumerating the steps (at a minimum, you must have one <step> element, which could be the entire task). There are other limitations as well in terms of what elements can come before and after the <steps> elements that some may find restrictive.
In DITA 1.2, which is being prepared for approval as we speak and is mostly implemented in the 1.5 version of the DITA Open Toolkit, there is a new, more generic form of Task that removes these restrictions.
In general, with DITA 1.1, the two constraints that most people run up against are the details of the Task content model and the fact that you cannot define arbitrary attributes for specialized elements (you can only define global attributes).
The solution to the Task issue is to either use DITA 1.2 or simply define your own task specialization (as long as it's not called "task").
The solution to the attribute issue is to use specializations of the <data> element instead of attributes where you need to define element-type-specific metadata.
The issues with Task in 1.1 are simply an accident of history, reflecting the design IBM had developed for its use and that was not relaxed when DITA 1.0 and 1.1 were developed.
The issue with attributes is a side effect of DITA having a sufficiently simple syntax for declaring specializations--any syntax that would enable per-element-type declarations of specialized attributes would be way too complicated for simple processors to use.
One of the advantages of DITA is that the specialization declaration syntax is simple enough that basic XML tools, including CSS selectors, can take advantage of it. But that value comes with a cost, and the attribute problem is one (another is the inability to enable namespace-qualified specialized elements, because there's no easy way to allow arbitrary namespace prefixes).
So there are a few constraints DITA has to impose in order to provide the otherwise very high value it does. It's definitely a case where implementing the remaining 10 or 20 percent of requirements would dramatically increase the implementation complexity of DITA-aware tools.
Post a Comment
<< Home