Author’s note

This presentation was originally designed as a visual aid. This copy has been modified to be more meaningful as a standalone document. Some speaker's notes have been added as text.

Session objectives

I would like to encourage you that you can learn about and figure out how to use DITA.

I want to show you—not just talk about—some of the things you do on your computer to create DITA documents. At one DITA conference I heard so much about DITA, but I was struggling with, how the heck does this work? What do you do?

I hope to explain in overview fashion how we went from zero DITA/XML knowledge to being able to publish four DITA documents within a year.

This is how we did it. You will have to figure out what works in your situation. I will tell you what worked in our situation.

Who is Hughes? What does Hughes do?

At Hughes (Hughes Network Systems) we sell and operate satellite networks. We provide Internet service by satellite.

Hughes has about 1600 employees. Our documentation group is small, with three full-time technical writers, a manager, and several contractors. I did most of the work for the DITA pilot project I will describe in this session.

FrameMaker has been our primary authoring and publishing tool for about 10 years.

Writers have to learn not to format

(You can laugh, but when this picture was taken I was working really hard. As you can see I was using both hands.)

Many of us are well-versed in DTP software such as FrameMaker. With DTP software you could control nearly everything about the format.

DITA is very different. As a writer creating topics or content for a DITA publication, you can’t format anything! You can make text bold, underlined or italic. But that’s about it! You can’t indent a paragraph, or select a font or font size, or select bullet styles. This can feel very strange and even be frustrating when you first start creating DITA topics. Someone else does the formatting—the person who creates or modifies the stylesheet.

A basic idea of DITA is that content is created separately from formatting. Formatting is applied to content as a separate operation.

DITA—you can do it

Making DITA work requires a lot of work and a lot of learning. But if I can do DITA, you can do DITA. And it’s very rewarding.

Things would probably go more smoothly if you have several people in specialized roles. If your company will pay for that, that should help your effort, but this isn't an absolute requirement.

Don’t be afraid to jump in. The more you learn about DITA, the less intimidating it is.

Our problem

Our problem—variations, inconsistency, keeping track.

We used FrameMaker to create an Installation Guide and a User Guide that shared a high percentage of common content. But there were also numerous differences. Eventually we had at least 10 manuals that had a high percentage of common content. It became hard to know what should be different in each manual, and when there was a need to add or revise information, we had to keep careful records to know which manuals needed to be changed and the status of changes.

Eventually we knew we were doing far more work than we had to, and it became hard to feel confident that the content was correct and consistent in the many variant documents.

This was our problem: We want all content to be exactly the same (so it’s not contradictory) where it should be the same. And where it should be different, we want it to be different. We wanted to achieve this without duplication of effort.

Our pilot project objective was to use DITA to produce four manuals in PDF form. DITA is well suited for managing content that is the same and content that is different.

Where to start?

Of course you’ll want to research DITA. What is it? What does it take? What are the benefits? etc.

We also researched DITA, primarily on the Internet. There are many sources of DITA information on the Internet, and several good DITA forums. The time I had for researching was critically important for learning about DITA. You can see from this graphic how easy it is to find DITA information on the internet.

Getting started – List topics

One of the first things to do is plan what topics need to be covered so you know what topics need to be created.

One suggestion: List topics from an existing manual if the document you want to create will be similar. Copy the TOC.

Create an outline or at least a list.

A spreadsheet can be very useful for keeping track of topics. You can include status, applicability, writer assignments, etc. If you get a CMS (typically later) you may not need the spreadsheet anymore.

Initially, you don’t have to worry about hierarchy and organization (but you can). You can determine these later.

What tool do you use for writing topics?

There are many XML text editors. Some are free; some are very expensive.

We chose XMetaL because it is: Highly rated, easy to use, completely designed for DITA, enforces DITA rules, validates content as DITA compliant, is very capable, and is stable.

I would like to point out that XMetaL has sponsored this session by paying my conference expenses, but they have not asked me to endorse XMetaL in any way. I’ve found XMetaL to be a very good tool, and anything I say about it is only because I want to say it and because it’s my honest opinion.

The main advantage of a text editor like XMetaL is that it knows the XML and DITA rules and it enforces them as you create or edit a topic. For example, you can only place certain elements within certain other elements... [Explain]. Writers don’t really have to know that much about DITA and XML, but they do have to learn to write topics. However, learning about DITA and XML will help them produce better DITA content.

Storing topics As I go on, I want you to think about:

What are we going to do with these topics?

How are we doing to use them?

How are we going to assemble the whole, larger document?

Your file and folder structure is important. You and the software you use, including output processing software, need to be able to find the files that are included in a ditamap.

To give you an idea of the scale of our project, we created 151 topics and 191 image files. We used these files to produce four manuals of about 95 pages (for the user guides) and 140 pages (for the installation guides).

However you organize your files, it’s worth some very careful thought.

Also, think about your file names. They can help organize content, help identify content, identify content type (c_, r_, t_).

Notice that a lot of the files start with the same word or words. This a way to keep files grouped by category, making it easier to find a particular file.

So how do you put the topics together?

At some point you've got 50 or 100 topics. What do you do with them?

This is the answer to the question I asked you to think about: Using DITA techniques, you string the topics together with a map. That is, you build a ditamaps to specify the content, hierarchy, and organization of the document.

A ditamap lists the topics that will appear in your PDF or other output type.

A ditamap can be made up of smaller parts called submaps.

A bookmap is a specialized ditamap that makes it easier to create chapters, appendixes, and an index, and other book-oriented parts.

Ditamaps allow you to be selective in two distinct ways: You can include or not include a topic. Or, you can include a topic and flag it as conditional—for example, include this topic for Product A but not for Product B.

Ditamaps can include submaps

Typically a submap defines a large subject area such as a chapter or appendix. For example, you might have a submap that includes all the topics for Installing your toaster and another submap for Operating your toaster.

How do you specify headings, such as Heading 1, Heading 2, etc.

You don’t.

If you’re used to FrameMaker or a similar program, it’s hard to imagine that a title that will be a heading is not tagged as something like Heading 1, Heading 2, etc. Insead, headings are determined by how topics are nested in the ditamap.

Conditional content

I think conditional content is one of the best features of DITA, and XMetaL makes it very easy to apply. When I figured out how to use conditional content, it was like a revelation. It was amazing how easy it was to apply, and how reliably it works.

You can conditionalize: A phrase. Two sentences. Table. Graphic. Even an index entry.

With conditional content you say this content—a phrase, a paragraph, a graphic—applies to A but not to B. When you create the PDF, you tell the rendering software to include everything that applies to A, or everything that applies to B.

It's great to be able to work on one topic or paragraph and know the work you're doing actually applies to four different manuals, as opposed to opening 10 documents to make a change in each.

Conditional content with DITA is really works, and it’s dependable. If you set up your topics correctly, you’ll see (in output) what you want and not what you don’t want.

How to add an image

What you really do is add a reference to an image file. Then at build time, when you create your PDF, the processing software puts the image into your document. And until then, most image editors can render the image on the screen, as shown on the next page.

XDocs

XDocs is the CMS we chose to use. It’s one of the least expensive ones.

It safeguards our data, prevents writers from overwriting each others’ work, helps us publish PDFs.

You have to check out a file before you can modify and save it.

Publishing – Conditional content There are different ways you can publish your topics to create a PDF. You can do it with XMetaL. We use XDocs (our CMS) to publish PDFs, mainly because this gives us a style/format that we like, and it simplifies some tasks. Remember our basic problem—producing 10 variations of manuals with similar but different content? This is the solution—applying conditional content when you create a PDF. We specify, for example: Include all content meant for an installer and all content for Product A. This builds a PDF for the Product A Installation Guide. The results are reliable and accurate as long as you have created your topics correctly.

So far we have produced four manuals with the exact same content where it should be the same, and customized content where we needed content to be different based on audience and/or product. This is the solution to our basic problem.

Nearly all the work of DITA is up front. If you invest the time to do things right—and test to make sure it’s right—you can literally press a button (or a few buttons) to quickly create an output file with a table of contents, index, and other book features.

If I can do it you can do it.

I started out with absolutely no DITA knowledge or skills. Thirteen months later we released our first two DITA-produced manuals (126 pages and 82 pages).

Don’t be surprised if you get to a point where you feel like you want to bail out because it just seems impossible to make it all work. I got to that point. But I’d like to encourage you to press on. I’m glad I did. And I’m still pressing.