1.1 uDoc Alternatives

Before choosing any documentation process to work with, it's important to look at all the options. No one process fits everyone, even if it seems to be a “standard”. Many standards have come and gone, like the grandfather of structured documentation, SGML.

The first question is, do you want topic-oriented processing, or is a document-oriented method better? The document-oriented processes include DocBook, now XML-based, as well as a large number of more proprietary systems, such as those based on FrameMaker and on Arbortext. If all the docs you produce are books for print (or for PDF on-line), you may be better off not trying to fit your use case into a topic-oriented system.

If you do need topic orientation, to enable widespread re-use of documentation parts in varying products, or to keep translation costs down by finer text granularity, or if your deliverables include on-line Help systems, you have many more possibilities to consider, some of which you may never have heard of before. In some areas, there are specialized needs that require industry-specific systems, as for aircraft, pharmaceuticals, and the military. There is also the possibility of designing your own system from the ground up, a very, very, expensive option but still one to consider.

One topic-oriented system that you almost certainly have heard of is Darwin Information Typing Architecture (DITA). Originally developed by IBM for its documentation needs, it has since become an OASIS standard. We at Omni Systems have worked with it very extensively, as the creators of an application heavily used for getting from FrameMaker to DITA (Mif2Go) and a second application for producing on-line Help and Word files from DITA (DITA2Go). We discuss its advantages and disadvantages at length throughout this spec.

We created uDoc largely in response to major shortcomings we saw in DITA, not just in the implementation of some tools (like the DITA-OT), but in the core design itself. We're not the only ones to come to that conclusion. The rest of this spec should give you a very good idea of how uDoc differs from DITA, and why.

There's another markup format with similar design goals to those of uDoc, called Project Mallard. The designer of Mallard, Shaun McCance, also started by studying DITA and DocBook, and had many of the same concerns we did. While uDoc supports a lot that Mallard doesn't, like footnotes, variables, indexing, glossaries, abbreviations, and generated lists, we feel Mallard is a worthy effort worth a long look, especially for Linux users, the environment in which it was built.

There is also SPFE, pronounced “spiffy” and created by Mark Baker, which is a database-oriented approach to structured documents. It directly inspired the addition of elements that can run queries on external resources in uDoc. This too is worh serious study; see its comparison to DITA.

Previous Topic:  Chapter 1. Why Use uDoc?

Next Topic:  1.2 uDoc Error Recovery

Parent Topic:  Chapter 1. Why Use uDoc?

Sibling Topics:

1.2 uDoc Error Recovery

1.3 uDoc Interoperability

1.4 uDoc Hierarchies

1.5 uDoc Development

1.6 uDoc Tag Minimization

1.7 uDoc Metadata

1.8 uDoc Element Types

1.9 uDoc Files