The DITA authoring/production framework

Creating an expansible DITA authoring and production system

One of the key questions for assessing DITA and DITA Open Toolkit is "What would it take to put together a DITA-based authoring and production system that would scale as my needs expand?" The answer depends on both your near-term goals as well as what you expect your ultimate system to look like. The information below lists and defines four "DITA maturity" levels: demo, pilot project, basic end-to-end system, and enterprise-level system, and the likely requirements for each.

Base components required

The base components, which apply to all levels, include the following:

Base skills required

The base skills, which also apply to all levels, include the following:

System maturity levels, and the requirements of each

Demo level

Materials written and processed at a demo level simply provide a proof-of-concept, or a way to demonstrate the end-to-end authoring and production processes. Two sets of such files (the garage sample and the grocery shopping sample) are provided with the DITA Open Toolkit User Guide package.

Only the base components and skills are required, unless you want to demo in a publishing environment other than XHTML (which is the default and assumed publishing environment, unless otherwise indicated).

Pilot project (prototype) level

You can do a pilot project with base-level tools and skills, without a library or content management system (CMS), and without doing extensive system-level integration. However, you may want to add the following to the base-level components:
  • Components to support additional publishing environments (for example, if you plan to publish HTML Help you will need the HTML Help compiler)
  • An authoring environment that supports DITA and has other features you require (for example, spellcheck and CSS support)
  • If you plan to include non-text content, a specialized editing component (for example, for image content, video, or Flash)
  • Tools for compiling and previewing your output in whatever publishing environment you are using (for example, you may want Microsoft's HTML Help Workshop, Sun's JavaHelp tools, or the Eclipse 2 Standalone Help System)
  • If you plan to produce printed deliverables, tools that provide FO processing and preview
  • Debugging and reporting tools, which may be available free or for purchase (such a toolset was created by the authors of this book, and is available free)
The following additional skills may be required:
  • A good understanding of your target publishing environment(s)
  • Some level of expertise with the DITA-aware editor
  • Skill with other tools you plan to use

Basic end-to-end system level

Individuals and organizations working at this level need to create a more formal process, and plan for the acquisition of tools that will serve at this level and also at the enterprise level, if project plans extend that far. This level may require processing scripts (perhaps even with user interfaces for setting parameters and saving profiles) that link the components together and provide consistency for repeatable processing. Branding is a probably a factor important for the DITA output.

At this level, documentation is part of a formal product cycle. The information development process probably involves multiple people. Producing output may be a collaborative process between the information development and product development organizations. Writers are probably required to follow departmental style and production guidelines. Information being developed goes through at least an informal review process. Candidate output documents may need to be formally verified or tested before being released.

When you move to this kind of production system, you may also need:
  • A make or macro component to program a sequence of processes
  • A packaging tool for distribution
Projects at this stage may require a number of additional specialized skills, for example:
  • Information architecture, planning, and workflow expertise
  • The ability to install and set up additional tools of a more complex nature
  • The ability to create and adapt XSLT
  • Graphic design expertise
  • User interface and user experience skills

Enterprise system level

This level has specific support for enterprise business rules, for editor wizards and for what the DITA architecture calls the "delivery context" layer (for example, true book-like output or specific mapping methodologies). The content may be translated into one or more languages. The distribution or fulfillment process is complex. A customer feedback mechanism needs to be present.

There is a need for extensive record-keeping, including the analysis of metadata. Content terminology and topics may be shared among a number of organizations (for example, marketing, technical writing, and training). There may be coordinated or shared content among other internal product or component development groups, or even external groups like business partners.

Writers may be required to adhere to an organization-wide set of style and terminology guidelines. Content may be formally reviewed by a group of editors, according to a complex schedule. Verification and testing is probably done by a separate test organization.

Tools at this level could include a library system, a content management system, business analysis software, and a customer feedback mechanism or system.