Working with DITA

Writing DITA topics

DITA topics are the basic units of DITA content.

Topics are the basis for high-quality information. Each topic is organized around a single subject or answers a single question.

Each topic is typically authored as a unit. It consists of a title, which captures the subject of the topic, and further content.

As stated in the essay paper: Introduction to the DITA architecture, DITA topics are organized by DITA maps. It is also possible to nest sub-topics within a topic. Specialization enables the creation of specialized topics and other units of content that are tailored to particular structural requirements. Content referencing (conref) enables fragments of content to be reused from a single source. Conditional processing permits a single source to support the needs of multiple audiences.

The architectural specification describes topics and information typing at

http://docs.oasis-open.org/dita/v1.1/CS01/archspec/topicover.html.

A 5-minute tutorial on DITA Topics is available as a Flash animation.

Editors for the Architecture area:

Working with maps

DITA maps collect and organize references to DITA topics to indicate the relationships among the topics. They can be used to identify the topics you want to include in a deliverable, and to create tables of contents and related links for the information.

Maps can organize topics into hierarchies, tables, and groups, and also have special elements for referencing other maps. You can use multiple maps to pull different deliverables out of the same set of topics, and to separate the concerns of managing deliverables and architecting information from the concerns of topic authoring.

The architectural specification describes DITA maps and relationship tables at

http://docs.oasis-open.org/dita/v1.1/OS/archspec/dita_spec_23_maps.html.

For a practical approach to setting up relationship tables, see

http://dita.xml.org/improving-relationships-relationship-tables

Controlling heading hierarchies using ditamaps

People often ask what to do to make extra headings and levels of hierarchy appear within a table of contents.

A common misconception is that if a map includes a submap, the title of the submap will appear as an extra heading in output. This does not occur. Also, the topics within the submap appear at the same hierarchy level as other topics that are peer to the submap itself; being in a submap does not cause extra "indenting".

To add an extra heading to a map, a good method is to use a <topicref> element pointing to a topic that contains a title and nothing else. This method is easy to manage for translation.

Another method is to use the <topichead> element. This element did not appear in PDF output using previous versions of the DITA Open Toolkit. However, version 1.4 of the DITA Open Toolkit does create headings from <topichead>.

Tools for modeling maps

The Information Architecture Workbench (formerly IBM Task Modeler) enables you to analyze the organization of your content and creates a corresponding DITA map along with stub topics for to-be-developed topics in the map.

This tutorial provides a quick but comprehensive introduction to using the IAWB to analyze and create a complete map of a sample scenario: IAWB Handout by Ben Welman.

Editors for the Architecture area:

Improving Relationships in Relationship Tables

A team encounters quite a few challenges when transitioning from unstructured to structured writing. For my team, the struggles associated with learning DITA and following the DITA structure were minor compared with the challenges presented by corralling hundreds of individual topics into a logical hierarchy. The biggest challenge we faced was managing topic relationships.

In DITA, related topics can be managed either in the DITA topics themselves, or via DITAMAPs using relationship tables <reltable>.

While topic relationships can be stored in the topics themselves, as products evolve and user interfaces change, a topic that was required for release 1.0 of a product may no longer be needed in release 2.3. If related topics are maintained at the topic level, removing a topic that is no longer part of the system may involve modifying the related topics of a dozen different DITA files.

However, if related topics are managed using a relationship table in a DITAMAP, removing a topic that is no longer needed involves changing only one file. Relationship tables can be used to easily manage the related topics that are associated with each DITA topic.

After doing a lot of research into relationship tables, my team nearly abandoned the effort because mapping a large number of topics in the standard three-column relationship table was too complex. However, once we realized that a four-column approach was much more effective in creating and maintaining the relationships between DITA topics, our information modeling and online help creation process became much easier to manage.

Example Files

To illustrate the benefits of a four-column relationship table, the following example topics will be used.

Concept Topics

The following concept topics are designed to introduce the subject matter to the reader. These topics will cover information ranging from, "What is it?" to "Why should the reader care?"

What is a user? (user_c.dita)
What is a role? (role_c.dita)
How are users and roles related? (user_role_c.dita)

Task Topics

The following task topics are designed to walk the user through a procedure that goes from step 1 to step N, with the end result being the successful completion of the task at hand.

Create a new user account (user_create_t.dita)
Edit an existing user account (user_edit_t.dita)
Create a new role (role_create_t.dita)
Edit an existing role (role_edit_t.dita)
Associate a user account with a role (user_role_associate_t.dita)

Reference Topics

The following reference topics are designed to support the user in completing a task. For example, if step 3 of our task instructs the user to complete field xyz, the reference topic for that window will describe field xyz and include supporting background information that may not appear in the task.

User Account window details (user_r.dita)
Role window details (role_r.dita)

Desired Outcome

Using a standard three-column relationship table and a four-column relationship table, the following relationships will be applied to each topic in the example documentation set:

Standard Three-Column Relationship Table

Each row in a relationship table defines an individual set of relationships between topics. In the relationship table diagram below, there are seven rows that are used to define the relationships between ten different topics. The difficulty in dealing with this type of relationship table is that the relationships for some topics are defined in multiple rows. So when a topic relationship changes, the writer maintaining the DITAMAP must perform a detailed analysis of the relationship between topics in several rows to enact a change.

In DITA, these relationships are expressed as follows:

Four-Column Relationship Table

While the four-column relationship table below has three more rows than the standard three-column relationship table, the larger table makes it much easier to maintain the relationships between the various relationships between the topics. In the example below, when a topic relationship changes, the writer can simply locate and modify a single row that defines the links for that topic.

In DITA, these relationships are expressed as follows:

Conclusion

Using a four column relationship table in our SunGard Higher Education DITAMAPs, we are able to easily maintain the relationships between hundreds of topics authored by a distributed writing team. Each team member can modify the specific row that applies to the topic in question without having to analyze the relationships of any other topic.

While proper up-front planning is still vital to assign topic relationships, knowing that each source topic is always located in the first column and all target topics can be found in columns based on the topic type has made the job of maintaining those relationships much easier. -->

-Zak Binder
Advisory Technical Writer
SunGard Higher Education
zak.binder@sungardhe.com

Working with content references (conref)

Content referencing (conref) is a convenient DITA mechanism for reuse of content from other topics or maps. A fragment of content in one topic or map can be pulled by reference into any other topic or map where the content is allowed. To create the reference, start by creating an empty element of the type that you want to pull in, and then use the element's conref attribute to provide the target's location.

The architectural specification describes content referencing at:

http://docs.oasis-open.org/dita/v1.0/archspec/conref.html

The language specification describes the syntax of the conref attribute at:

http://docs.oasis-open.org/dita/v1.0/langspec/id-atts.html

Editors for the Architecture area:

Working with conditional text

Conditional processing, also known as profiling, is the filtering or flagging of information based on processing-time criteria. The filtering mechanism first matches against the criteria, and then takes a specified action.

DITA provides several built-in attributes to hold the values for filter criteria for an element. These are:

audience
platform
product
otherprops
rev (for flagging only)

It is possible, for example, to specify the platform or audience that a particular paragraph applies to. The values of these attributes can then be leveraged by any number of processes, including filtering, flagging, search, and indexing.

There is a proposal for DITA 1.1 that will enable specializers to define their own metadata attributes for use in conditionally processing content.

The architectural specification describes conditional processing at

http://docs.oasis-open.org/dita/v1.0/archspec/condproc.html

Editors for the Architecture area:

Publishing with the DITA Open Toolkit

The DITA Open Toolkit, or DITA-OT for short, is a set of Java-based, open source tools that provide processing for DITA maps and topical content. You can download the DITA-OT and install it for free on your computer, or you may already have a copy bundled together with your authoring tool or CMS.

The DITA-OT transforms DITA content (maps and topics) into publishing deliverable formats such as web (XHTML), print (PDF), and Help (CHM and Eclipse). Output files are generated in your file system, in a directory of your choosing. During the publishing process, the toolkit runs a set of "pre-process" routines that resolve conref, keyref, and implement several other standard DITA behaviors.

If you do not have a tool that embeds the toolkit, you will need to install it first; instructions are available at http://dita-ot.sourceforge.net/latest/.

Using your help authoring tool to publish

The OT is integrated into many authoring tools (e.g.,FrameMaker, <oXygen/>, XMetaL) and content management systems (e.g., Astoria, Bluestream, IXIASOFT, XyEnterprise). Most of these tools provide their own menus or GUIs to interact with the toolkit. Consult your tool's documentation to find out if such tools are available.

Publishing with other GUI tools

There are currently two external GUI tools that may be used to run a toolkit build. These tools are not maintained by the DITA-OT developers; they are created and maintained by users outside of the core development team.

"DITA Open Toolkit GUI" is a simple, open source Java-based GUI that allows you to select an input map, DITAVAL filter file, output directory, and transform type. The tool is hosted at SourceForge: http://sourceforge.net/projects/ditaotgui/
WinANT Echidna is a Windows-only tool that provides access to many more toolkit options. It also allows selection of different skins, so that common sets of options or style branding may be saved or reused. This tool is not open source, but the binary is available for free at SourceForge: http://sourceforge.net/projects/winant-echidna/

Publishing with Ant

For those not using a GUI or authoring tool, the best long term approach to builds is to use Ant. An Ant build file provides you with an easily repeatable build; the time investment is entirely in the initial definition of the build file.

The toolkit includes several sample Ant files in the samples/ant_sample/ directory. When creating your first Ant build, it's a good idea to copy the most appropriate build file to a new location, edit it to change the input file and base directories, and add any additional options as needed. A good current resource for available Ant parameters is the "Ant Quick Start Guide" (http://sourceforge.net/projects/antquickstartgu/); that information is currently being updated and should be integrated into the DITA-OT's doc/ directory sometime in July or August 2010.

Publishing using the Ant Demo

The toolkit also comes with a demo Prompted Build using Ant; this method prompts for the input file, output directory, and transform type, but does not allow access to any other options. To run the demo, run the following command from a DOS prompt in the root directory of the toolkit:

ant -f build_demo.xml

Publishing with the Java command line

The final way to run a build is with the Java command line. This is simply a Java based wrapper that takes in a list of parameters, creates an Ant build file, and then runs an Ant build as described above. The primary purpose of this build method is for one-time builds or for getting to know the toolkit, because it allows access to most processing options without the need to create an Ant file. Of course this method may be used to run any number of builds, but those concerned about memory usage should know that this is no different than running an Ant build together with a small extra Java process.

To get a list of all options available to the Java command line, run the following from the root directory of the toolkit:

java -jar lib/dost.jar

A full build using the shipped sample files would look something like this, which uses the /i parameter for the input file, /outdir for the output directory, and /transtype to select an output type of XHTML:

java -jar lib/dost.jar /i:samples/hierarchy.ditamap /outdir:out /transtype:xhtml

Other resources:

Overview page for information about The DITA Open Toolkit
Descriptions of the available DITA-OT Packages

Simple Interface For Plugin Installation and Upgrade

Problem: Manual Installation Process

Installing a plugin takes two or three steps, depending upon the platform and installed software.

Unzip the plugin package
Copy the generated directory into the “demo” or “plugins” folder
Run the integrator task

Steps 1 and 2 may be combined on many platforms, if the user knows how to “target” the unzip of a directory appropriately.

This process is actually pretty error prone. Reported user mistakes include:

creating a directory and then unzipping the package into it (resulting in an extra directory)
running the integrator task in the wrong directory

Problem: Automated Installation Process

A software developer or system administrator wishes to make scripts that will automatically install a set of plugins. Today, this installation process necessarily depends upon the directory structure of the DITA Toolkit. This makes reorganizations of the toolkit potentially backwards incompatible.

Proposal

Given a properly configured DITA toolkit, installing a plugin should be a single step, like

java -jar lib/dost.jar /plugin:”c:\My Download Files\FrameMaker_adapter.zip”

No matter what the directory structure of future DITA toolkits, this command line will remain invariant and will copy the right files to the right places.

This implies a fixed structure for plugins. The proposed structure is as described below.

Plugin Structure

A DITA toolkit plugin is a zip file consisting of a single top-level directory. This top-level directory must contain a file called “plugin.xml”. It will typically contain main other files but this standard does not address the structure of those files.