Going from using a software like MS Word to using DITA for documentation is somewhat like going from manually machining a metal rod on a lathe to programmatic machining using a CNC machine. DITA lets you incorporate intelligence into your documentation. Let’s look at the first stage of the planning that needs to be done to adopt DITA.

The Challenge

One of the first challenges that you will face going from MS Word to DITA is thinking in terms of Topics instead of Documents. One of the first rules of DITA content creation is that a topic should be as short as possible and it should contain only one type of content. For example, lets say that you are creating documentation for cleaning a car. Then the topic of your documentation where you talk about cleaning the tyres of the car should not include steps on how to clean the under body of the car. The tire cleaning topic should only be about cleaning tires.

You need to take this topic mind set all the way. To explore this further, let us look the user manuals that a hypothetical car cleaning service. Let us also imagine that they service 25 different types of cars and car cleaning process for each car (although similar to a large extent) is a little different. To further our cause, I am going to further imagine that they have 25 user manuals in MS Word format. The service manager now wants use DITA to manage and produce the documentation.

The imaginary manager of the car cleaning service has handed you one of the user manuals and the table of contents of the user manual looks as shown below.

Table of Contents

1. Introduction – The importance of keeping the car clean
2. Cleaning the Exterior
   1. Washing the Body
   2. Cleaning the Windows
   3. Washing the Tires
   4. Washing the Under body
   5. Waxing and Polishing
3. Cleaning the Interiors
   1. Cleaning the Carpet
   2. Cleaning the Seats
   3. Cleaning the Dashboard
   4. Cleaning the Doors
   5. Cleaning the Glass Surfaces
   6. Cleaning the Boot
4. Keeping the Car Clean

Now let us look at how you can take this user manual to plan your DITA conversion. The first step would be to create a table like one shown below. The table of contents of your user manual document will be your guide.

Table of Contents to a DITA Map

#	Original User Manual TOC	DITA Map	Topic Type
1	Introduction – The importance of keeping the car clean	Introduction to Keeping Your Car Clean	Concept
2	Cleaning the Exterior	Cleaning the Exterior	Concept
2.1	Washing the Body	— Washing the Outer Body	Task
2.2	Cleaning the Windows	— Cleaning the Windows	Task
2.3	Washing the Tires	— Washing the Tires	Task
2.4	Washing the Under body	— Washing the Under Body	Task
2.5	Waxing and Polishing	— Waxing the Polishing	Task
3	Cleaning the Interiors	Cleaning the Interiors	Concept
3.1	Cleaning the Carpet	— Cleaning the Carpet	Task
3.2	Cleaning the Seats	— Cleaning the Seats	Task
3.3	Cleaning the Dashboard	— Cleaning the Dashboard	Task
3.4	Cleaning the Doors	— Cleaning the Doors	Task
3.5	Cleaning the Glass Surfaces	— Cleaning the Glass Surfaces	Task
3.6	Cleaning the Boot	— Cleaning the Boot	Task
4	Keeping the Car Clean	Keeping the Car Clean	Concept

How to Classify the Topics

To understand how to classify the topics in valid DITA topic types, you need to understand the various DITA topic types. The table like one shown above is possible if you audit each of the topic in your user manual and try to classify the topic as any one of the following types:

1. Concept – Click here to know more about DITA Concepts
2. Task – Click here to know more about DITA Tasks
3. Reference – Click here to know more about DITA References

Once you have classified the topics in the user manual it becomes very easy to make the classification. In the next post I will go into further detail of taking an example topic of the existing user manual and converting that to a DITA topic.