"DITAworks is an Eclipse based solution which is built on DITA architecture and supports collaborative modeling, maintaining, publishing of complex documentation arrays."

*instinctools GmbH
Home Forum Blog Product Contact
Entries RSSEntries RSS   Entries RSSComments RSS

Archive for the ‘Problems and Solutions’ Category

Support of glossaries in DITA and DITAworks.

Monday, October 12th, 2009 by Alexej Spas

Very often in technical documentation area we are coming to need of publishing of terminology glossaries. DITA provides a way to define glossaries with some important aspects to keep in mind. This article explains specifics of glossaries support in DITA 1.1 and DITA 1.2. It also describes how DITAworks supports generation of glossaries. (more…)

Posted in Features, Problems and Solutions | No Comments »

DITA Eclipse Editor: Using DITA for publishing documentation in Eclipse Help format. Functionality preview

Monday, April 27th, 2009 by Alexej Spas

This article discusses the main challenges that a documentation team faces when it decides to use DITA as a source format for Eclipse Help documentation. It also explains how DITAworks documentation tool plans to address these challenges.

About Eclipse Help

The Eclipse Platform includes its own help system based on an XML table of contents referencing HTML files.  This is a standard way to document Eclipse-based software products.

But eclipse help format is not reduced to usages only inside of Eclipse platform. It is available as standalone server solution and can be used for providing ANY help content via Web server. Eclipse help system provides such important functions like navigation through TOCs, search, indexing, bookmarking and s.o.

When Eclipse help is used for documentation of Eclipse-based software, it allows much more sophisticated mechanisms for context-dependent help definitions like: search expressions, contexts, so called cheat sheets and s.o.

Additionally, due to component-oriented architecture of Eclipse, Eclipse help is structured in form of plugins that can be independently deployed and interlinked. This enables creation of scalable documentation that fits to complex product configurations.

Eclipse Help and DITA

DITA as single-source architecture opens a promising approach for maintaining all your documentation in single format. Eclipse help as one of the publishing formats can address needs of context dependent application help as well as generic online help.

DITA Open Toolkit provides a way to transform DITA maps and topics into Eclipse help plugins, but these possibilities are quite limited. Namely DITA OT will generate a TOC file and set of HTML topics linked to source map, but it does not address following important specifics of Eclipse Help:

  • Definition of contexts (used for context-dependent help)
  • Interlinking topics between several Eclipse help plugins
  • Definition of search phrases
  • Definition of cheat sheets
  • Tuning of plug-in contents (Manifest properties, amount of TOCs, indexes, contexts and s.o.)
  • Some other advanced features of eclipse help.

These limitations are hindering adoption of Eclipse help as publishing output format for DITA content.  They need to be addressed if we want to use the full capability of Eclipse help system and this issue can be seen as a current challenge for DITA-oriented tooling.

(more…)

Tags: , ,
Posted in Coming soon, Features, Problems and Solutions | 2 Comments »

Common errors in DITA specializations

Saturday, March 28th, 2009 by Alexej Spas

DITA as information architecture can be seen as a set of best practices for topic-oriented authoring. Besides providing a set of DTDs and rules for authoring, DITA also defines a way to design new information structures customized through custom semantics. This is achieved by process of specialization.

Specialization opens a new dimension for customizing DITA to needs of different enterprises. But doing a valid specialization is not a trivial process. It requires rather deep understanding of DITA internals and command in technologies like DTD, XML Schema and s.o.

But even with sufficient knowledge of DTD (or XML Schema) coding, doing a valid specialization requires knowledge of certain DITA principles and rules. Just designing a valid DTD will not necessarily mean that you have a valid DITA model. More on Specializations can be read here: http://docs.oasis-open.org/dita/v1.0/archspec/ditaspecialization.html

This article discusses some common problems and pitfalls people face when they do DITA 1.1 specializations . (more…)

Tags: , , , ,
Posted in Problems and Solutions | No Comments »

DITA Models single-sourcing: Why not?

Wednesday, February 18th, 2009 by Alexej Spas

It is a well known fact that DITA is a great information architecture that enables single source publishing of content into different formats. “Write once and use everywhere” is a motto of it. But when it comes to DITA definition itself and DITA specializations, we have to make decisions about format we want to maintain our models in. We need to choose between DTD or XML Schema. Once this decision is made and the model is developed, it is quite a time consuming operation to change chosen format and in most cases, people would stay with originally selected format because of the effort and time involved.

DITA itself has to be supported in both formats in parallel.

But why not consider single-sourcing of DITA models? I think this would be logical step following the single-sourcing philosophy of DITA.

(more…)

Tags: , , , ,
Posted in Problems and Solutions | 2 Comments »




Copyright © 2008-2010 * instinctools GmbH