For authors and others embarking on implementation of Darwin Information Typing Architecture (DITA), it can be very helpful to get a preview of exactly what you’ll be working with before the implementation gets underway. This article answers the typical question authors have: what does DITA look like?
Keep in mind that DITA is an XML-based standard, which means that content no longer has the formatting of word processing or other authoring tools. Instead, authors put content within specific elements, which are semantic—they indicate the type of information that is contained within them. If you’re still a bit unfamiliar with DITA itself, make sure to read our post on what DITA is.
I’ve displayed three screenshots of the same content, first in FrameMaker, then converted to DITA (also in FrameMaker, although you could open it in whichever XML editor you choose).
First, with a very basic set of paragraph styles, here’s the content in plain FrameMaker.
Sample DITA content in plain, unstructured FrameMaker
Here’s the same content, now converted to DITA and viewed as code:
Sample content viewed as source code.
You can use a variety of tools (again this screenshot shows FrameMaker) to view exactly the same content in a more WYSIWYG manner with element tags, like this:
Sample DITA content in a WYSIWYG FrameMaker view
The formatting you see in this example (font size, font type, numbering, kerning, etc.) is for convenience’s sake only and is controlled by FrameMaker template files “under the hood.” The FrameMaker template files are completely customizable. Other XML editors use a set of CSS files to control the look and feel.
The formatting you see in any XML editor does not reflect the published format, which is controlled separately through your publishing tool. For example, you can customize the DITA Open Toolkit to create the formatting you want for fonts, page layout, title pages, Tables of Contents, etc.
A More Profound Change
However, transforming your content to DITA involves more than just about putting content inside elements. While these shots of parallel construction help illustrate how DITA works, they are not a realistic representation of what it means to move from unstructured content to DITA. Ordinarily, the content you’re moving into DITA wouldn’t be written in this unstructured format in a way that adheres to DITA’s topic-based writing paradigm.
DITA’s topic-based writing means that you separate information into discrete (searchable, usable) blocks and then bring them together again. You’re moving away from a book-based paradigm to a “chunked” paradigm, and this shift profoundly affects the way you write your content. Your documentation no longer has introductions on chapter pages, topics that refer to each other, content that flows in a chapter or between chapters. Topics are more focused so that they able to stand on their own, to be accessed in any order, and to be reused wherever needed.
For example, in the file extension content above, the unstructured content would in reality have included other related information, such as another set of steps for a related procedure or information about the control panel where the file extensions that are frequently found. And likely, that information would be all jumbled together in that same “space,” not because the writer is trying to be unhelpful, but because they have a “chapter” to write in and the space to expand. In DITA, all those different pieces of information are in their own, appropriate spots. So in our example, we would place information on file extensions in a reference topic (its own topic and file) and create separate task topics (with their own files) as well.
Writers who are used to writing short topics, particularly for online help, tend to find the change the least disruptive. Writers who are used to writing long books, with parts, chapters, summaries, and introductions will have a steeper learning curve and, at least initially, have to do more re-writing (or separating of content out into different topics types).
The great value in DITA from a content perspective is that focusing topics on one type of information (like a procedure) and one goal (viewing file extensions on its own, not combined with anything else) makes the content that much more usable and findable by the end user. DITA gives you the building blocks to enable you to improve the quality and usability of your content enormously.
