FLOWiki

(y)our wiki about all things technical communication

User Tools

Site Tools


dita:multi-channel_publishing

Multi-channel publishing

Multi-channel publishing is publishing documentation in different output formats, such as webhelp or pdf.

One of the great advantages of DITA content is its ability to be published in many different kinds of output formats. Its characteristic re-use strategies along with conditional processing were designed with efficient content-managing and publishing in mind. Essentially, one single source can become many different types of documents.

Structure vs. lay-out

DITA is an ideal writing tool as it helps you organize your content into specific elements embedded within a larger, universal structure. These structuring elements have nothing to do with a lay-out, instead they are fixed compartments in which you store your documentation. This also means that when your documentation is fully written, the DITA file cannot be published and immediately used as is.

The advantage of this universal (and free, open source) structure is that it can easily be opened in other programs more suited for publishing, such as publishing tools or DITA processors (oXygen, XMetaL), which will do the transformation for you. They transform your base DITA files into a publishable file of your choosing, and in doing so, apply a new lay-out on top of the structure. Lay-out, in this sense, is merely a layer that makes the structure more visible and accessible to the reader.

It is important to understand that the underlying structure is not changed when the DITA files are transformed. Your content does not change; it is merely put in a new outfit more suited to your needs.

In summary:

DITA structure Lay-out
Focus on content Focus on appearance
Fixed in unchanging elements. Options change from program to program.
Will remain the same in different programs. Might change if a document is opened in a different program.
Adheres to strict DITA rules. Adheres to rules of the individual programs and to the user’s preferences.
Allows the user to focus on content. Can distract the user from writing content.

Publishing

During publishing, the DITA structure is used as the skeleton on top of which a skin of lay-out is applied. This publishing process involves a number of steps that interpret DITA maps, resolve conref elements and cross-references, apply formatting numbering and labels, and map DITA elements to output format elements.

During this process, the content is given a new look according to the requirements of the output format. Since normal computers usually have much larger screens and are differently used than tablets and smartphones, the output also needs to be presented differently on these different devices. Each device type has its own conventions and requirements, such as button size, font size, resolution etc.

Publishing strategies

There are several ways of publishing your documentation:

These ways can be grouped into two main methods for publishing documentation:

  • The first method is by using the DITA OT (Open Toolkit) that is embedded in many DITA editors, such as oXygen XML Editor. This makes the publishing process easier as you can apply the type of transformation you want directly to your files, using the same program in which you’ve written them. Your processor will then run the files through the toolkit and generate the output you want.

    While using the OT is easy at first, it may require a lot of work and understanding of the processes involved to achieve a proper result. More often than not, the output from the OT gives your text a very basic lay-out. When you write and publish for different clients and different products, you might need varying lay-outs. Therefore, you might need to adjust the process manually to achieve the desired result.

  • A second method that avoids this issue is DITA2PDF. Essentially, it involves using an intermediary program in which you can adjust the template of your lay-out accordingly before you publish to PDF. While it might still require some searching and puzzling, intermediary programs such as FrameMaker and Word tend to be more user-friendly and allow you to apply your desired lay-out template in one go.
dita/multi-channel_publishing.txt · Last modified: 2017/03/30 13:16 (external edit)