Archive for the ‘DITA’ Category

Topic-based authoring

November 3, 2011

Topic-based Authoring is an approach to developing end-user documentation that explicitly identifies and uses topics as a fundamental organising principle.

It is a set of practices, processes, tools, and an organising conceptual framework.

Topics are present in all human communication, but they are often implicit and not utilized as a formal organisational principle.

Contrast “writing to make the sentences and paragraphs clearer“, on one hand, with “writing to make the thinking clearer“, on the other.

The first – writing to make the sentences and paragraphs clearer – involves interaction with words and sentences, which can be explicitly identified and whose relationships can be formally described.

The second – writing to make the thinking clearer – involves interaction with topics.

When topics are implicit there are no terms to describe topics, and no vocabulary to describe their interaction and relationship. Authors can intuitively deal with and structure information without an explicit vocabulary for topics, but capturing and communicating practices and standards, and creating processes around those, is impossible.

Topics become explicit first when they are a participant in the universe of discourse of authors. This can be thought of as weakly topic-based authoring. In this stage authors know what topics are, can see them in existing documentation, and may even use them as an organising principle while planning and writing. However, there is no specialised tooling support for topics, and the topic does not have an existence beyond an organising principle in the mind of the author.

Topics become completely explicit when they become first-class citizens, with a formal existence and participation in documentation workflow from planning to implementation as an organising principle with support from tooling. This is strongly topic-based authoring. In this stage topics are both used as an organising principle, and also have a physical existence in the workflow and toolchain.

Topic-based authoring (either weak or strong) produces the traditional output media expected by users, such as books, articles and help files. However, it can also produce enhanced output such as dynamic websites.

Topic-based authoring is used by companies to aid in information planning and project management, increase automation, decrease maintenance costs, and increase reuse (including multiple output structures from the same content).

Advertisements

Docbook 5.1 and topic-based authoring

June 4, 2011

Docbook 5.1 adds support for topic-based authoring. It’s studiedly neutral in its approach to topic-based authoring, in contrast with DITA’s almost religious zeal for the historical inevitability of the Topicalypse.

Without naming any names, the Docbook Definitive Guide V1.3 states:

One modern school of thought on technical documentation stresses the development of independent units of documentation, often called topics, rather than a single narrative.

It’s clear from this that the Docbook Technical Committee did not arrive at the topic epiphany by contemplating their navel in isolation, or by a blinding flash of light on the road to Damascus. And while no names are mentioned in this introduction to a pragmatic concession to topic-based authoring, Docbook 5.1 incorporates most, if not all of DITA’s features, while maintaining Docbook’s core strength of static linear narrative targeting a book-like output medium.

One thing that really screams: “Come to the mountain!” is the ability to build Docbook 5.1 topic-based output incorporating DITA topics. Just-in-time xsl processing (<transform>) is used to incorporate existing DITA topics in Docbook 5.1 topic assemblies, allowing you to come back to the fold without an expensive conversion of existing content.

Docbook 5.1 lacks the topic-based purity of DITA, implementing a dual (but isolated) static linear narrative / modular topic model, in contrast to DITA’s focus on topics uber alles, and adopting a pragmatic, descriptive approach (“hey, looks like people want to do this“), rather than a religious, prescriptive approach (“this is the one true way!“).

However, it looks to have learned from DITA, including DITA’s shortcomings, and brings its rich semantic model to the table, as well as its installed base of expertise and tooling.

A pragmatic approach is the approach that organisations need to take when moving from a pure static linear narrative approach to a modular topic-based one, so Docbook’s pragmatic compromise, along with its tooling maturity, may sit well with many organisations moving in that direction.

Syntext Serna 4.2 and DITA support

May 26, 2010

Oh, one more thing while I’m at it:

There seems to be a problem with the DITA 1.1 templates included with Syntext Serna 4.2 (the Open Source version, of course). The xml generated by the template contains both xsd and dtd declarations.

For example:

<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
<concept xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="concept-1" xsi:noNamespaceSchemaLocation="urnasis:names:tc: dita:xsd:concept.xsd:1.1">

You can see there a Doctype declaration, which invokes the DTD for validation, followed by an xsd declaration as an xmlns attribute of the concept element.

The problem with this is that either xsd or dtd should be used as the xml schema, not both. If both are present Xerces will attempt to do both types of validation. When it does DTD validation it will fail, because an xsd declaration is not part of the DTD.

Putting both types of validation into the template looks like a bug. If you create a new DITA 1.1 Concept from the template, and then Publish > HTML, it produces the error:

[pipeline] Using XERCES.
[pipeline] [Error] :4:155: Attribute "xmlns:xsi" must be declared for element type "concept".
[pipeline] [Error] :4:155: Attribute "xsi:noNamespaceSchemaLocation" must be declared for element type "concept".

My workaround has been to edit the template files in

plugins/dita/oasis-dita--11.sdt

and remove the xsd declaration. DITA topics created with the templates then validate fine using DTD validation.

DITA-OT 1.5 and Java version

May 26, 2010

I’ve been doing some work with the DITA Open Toolkit 1.5 lately, and got no love from Google on this issue, so here’s my contribution to anyone else who finds it:

If you are trying to build and get an error like:

DITA-OT1.5/build_preprocess.xml:80: java.lang.StringIndexOutOfBoundsException

Then check the version of your Java. I got this error with Java 1.5, and resolved it by switching to Java 1.6.

I’ll have something more to post about DITA soon, but I just thought I’d get that out there for anyone else who is scouring Google in vain.