tekom-Jahrestagung 2012 - ActiveDoc

Professionelles Schreiben / Technical Authoring
TA 2
Working with a Style Guide within DITA
Tony Self, HyperWrite, Melbourne, Australia
Overview
As more companies implement DITA to streamline the development of
documentation and user assistance, best practices for DITA authoring
are being established. While the OASIS DITA standard provides rules
for the use of elements and attributes, it does not provide clear guidelines
for how to practically apply the mark-up, and how to create consistency
so that DITA documents can be more readily interchanged. In
traditional authoring, a style guide would provide real-world examples
and clear recommendations. However, existing style guides are written
for style-based authoring, and not for semantic authoring. Dr Tony Self
has analysed the way in which DITA has been used, and has developed
a DITA Style Guide to fill the gap between the DITA standard and traditional
style manuals. Consistent mark-up enables efficiency of authoring
and interchange of documents, and standard approaches create
simple solutions to mark-up dilemmas.
The Problem
Although DITA is a standard, mark-up semantics can be applied in
non-standard ways. If DITA topics are really going to be interchanged
freely between members of a team and even between companies, DITA
authors have to apply DITA semantics consistently. The DITA language
reference helps a little, but what helps more is a style guide. This was
the motivation for the development of “The DITA Style Guide”.
Context
While the DITA technical standard is precise, the DITA approach itself
is not universally understood or agreed. Working with DITA is made
difficult by the lack of agreed common practices, let alone best practices.
Common practices must be adopted so that the advantages of the modular,
XML-based DITA document architecture can be realised.
Best practices for technical communication are typically captured in a
style guide. Tony Self embarked on a research project, as part of his PhD
by artefact and exegesis, to discover what constitutes best practice in
DITA, and how this information could be encapsulated. The product of
that research was “The DITA Style Guide”, which was first published in
March 2011.
Influences on Technical Communication
The advent of DITA and other structured authoring approaches is the
result of strong influences on technical communication. Twenty years
ago, technical publishing was simple, as the deliverable was almost always
a printed document, the product line that the document supported
was relatively simple, and the production lead times were lengthy.
The environment is vastly different now. There are different “delivery
platforms”, ranging from embedded user assistance, to Web, to eBooks,
to synthetic voice… in addition to the venerable printed book. Product
life cycles are incredibly short. In the software industry, programming
tekom-Jahrestagung 2012
385