Documentation Solutions

Solutions for authoring, publishing, and managing documentation

Author, Publish and Manage

A word processing or desktop publishing application typically represents a complete documentation solution, because no additional tools are required. In contrast, DITA-based solutions typically involve three separate components for authoring, publishing, and managing documentation.

Authoring Diagram

Author

Authoring tools based on the DITA open standard fall into two general categories based on the intended user type. Full-featured editors are designed for people who write documentation full-time (i.e. technical writers). Two popular full-featured editors are Adobe FrameMaker ($1000) and Oxygen XML Author ($550).

Simplified editors are designed for people who only write documentation periodically (i.e. engineers). They generally provide fewer features, but are much easier to learn and use by occasional users. Simplified editors include Adobe FrameMaker XML Author ($400) and Codex ($300).

Publishing Diagram

Publish

Standalone publishing applications convert DITA documentation source files to one or more delivery formats (PDF, HTML, WebHelp, mobile formats). Products in this category include the DITA Open Toolkit (Free), XMLMind XSL Utility ($260), WebWorks ePublisher ($795/year) and DITA InPrint ($2000).

Many editors also include publishing capabilities, and using an editor strictly for publishing can be simpler and more cost-effective than using a standalone publishing tool. For example, engineers may use a simplified editor like Codex for authoring, while their manager uses a full-featured editor like Adobe FrameMaker ($1000) or Oxygen XML Author ($550) for publishing.

Content Management Diagram

Manage

Only a few content management capabilities are typically required for basic modular documentation. This includes the ability to maintain incremental versions of document components, and the ability for multiple people to work on documentation without overwriting each other (ex. checking-out/in files or merging files).

If your organization already uses a source control system or document management system, then using that same system for your documentation can avoid additional licensing, setup, training, and support costs. If not, there are several freely available source control systems that are widely used for software development, but are also suitable for documentation: Subversion, Git and GitHub, and Mercurial.