Create DITA content

Discussions about DITA often include questions about writing topics, tasks, concepts, and references. This article isn't about the best practices and a complete overview of writing content, but rather a sample of a process to consider when you create DITA content. There is also no discussion of legacy file conversion here.Initial creation of content should include planning. The plan should include several core steps:

1. Identify the audience. Based on who you write for you can determine what to write, and what logical assumptions can be made.

2. Create an idea list. Ideas about what people may want to learn, do, or look up and is a brainstorming session lead to clear topics.

3. Identify topics by type. These topics become your tasks, supporting concepts and references, and, when needed, generic topics.

4. Develop the title and short description. These are the shell of your documentation and become core components of a prototype.

5. Populate with content as it is provided.

Consider the following example.

Identify the audience

I'm on a conf call, with the development team. They tell me that there is a new product and it allows people to create, edit, save, close, open, and print content. My notes document the features, but I'm also thinking about what the audience wants to do. On the topic of the audience the identification is made that the software is for people who are new to computers and looking to use a tool to create content such as a text based document, with some charts and graphs and images, as well as tables, basic web links, and other common features of a word processor.

Create an idea list

Now I know the audience and move to the big list of things this audience needs to know, or wants to do. The list is pretty comprehensive, but a recurring theme is to store and retrieve content. Based on my audience I know that core tasks they want to accomplish include being able to create a file, save a file, close a file, and open a file. However, it is possible they need some background information on some of these, and some technical information.

Identify topics by types

Knowing what I do about my audience, and what they want to do, I can further streamline my initial list of ideas into topics. It is likely that this list may grow and change early, but the goal is to stabilize it and then write exactly what is required, and nothing more. I use big picture classifications for the data. Tasks (what they want to DO), concepts (background ideas they need to KNOW to do a task), references (technical specs that they may LOOK UP if they are already familiar with the task), and topics (anything that does not cleanly fall into the other three categories).

The list includes the following topics:

• Saving your content (generic topic)

• What happens when you save (concept)

• Save content (a task with core ideas of how the user accomplishes a goal)

• File types (reference information that people may opt to look up)

Develop the title and short description

Then I write the titles and short descriptions for each. A title is unique in the way that it is written to guide my reader to a logical conclusion (so I may opt to avoid gerund(-ing) based titles for tasks, but use them for topics, and so on) and to provide an easy way to identify topics of potential interest. The shortdesc should provide value by enhancing the use of what I write without repeating the title.

Consider content for a generic sample of content, such as documenting the saving of files with a mix of topics, tasks, concepts, and references.

Topic

I may have a big picture topic titled Saving your content that introduces the idea of saving, without any major value. It's likely the main heading and a blurb. The file may be called Save.xml and the name gives away very little other than it being a generic chunk of content. It may look like the following in a word processor:

Saving your content

As you create documents, spreadsheets, slideshows, pictures, or just about any type of electronic content, you can store it for future recovery.

That's it. A very generic sample. In XML it may be this:

<topic><title>Saving your content</title><shortdesc>As you create documents, spreadsheets, slideshows, pictures, or just about any type of electronic content, you can store it for future recovery.</shortdesc></topic>

Then I have three other topics. They are NOT nested, they are all standalone files. They have no relationship. They are written as unique chunks of info. Perhaps, if the map permits it, they will be assigned a set of logical relationships, but for the time being I want to write each as a clean, concise and standalone chunk of content.

Concept

My next component is a concept titled What happens when you save which includes info on why you should save, and maybe a very big picture idea of what happens when something is saved. It may appear as seen here:

What happens when you save

After creating content you store the information to a specific location which may include a removable memory device, a local hard drive, a remote server, or even an online location.

The code for it may look like the following:

<concept><title>What happens when you save</title><shortdesc>After creating content you store the information to a specific location which may include a removable memory device, a local hard drive, a remote server, or even an online location.</shortdesc></concept>

Task

The task may have a very brief shortdesc to support the title as seen here:

Save a file

Any document can be saved. If saved for the first time, you are prompted for additional information.

A second task may be required to distinguish between the traditional Save option and the Save As option.

Save a copy of a file

Content that is modified can be saved with a new name, or to a new location, and leave the original file unchanged.

Reference

The reference may appear as seen here:

File types

Numerous file types can be selected when performing file level commands such as open or save.

Populate with content

Once the outline of your content is created, topics populated, and content reviewed, you can start to populate content. By using a map in DITA you can also publish topics that are related. This published output could take on several formats, but in part, it could appear as:

Saving your content

As you create documents, spreadsheets, slideshows, pictures, or just about any type of electronic content, you can store it for future recovery.

What happens when you save

After creating content you store the information to a specific location which may include a removable memory device, a local hard drive, a remote server, or even an online location.

Save a file

Any document can be saved. If saved for the first time, you are prompted for additional information.

Step 1: Select File > Save,

Step 2: If prompted, add file information.

Save a copy of a file

Content that is modified can be saved with a new name, or to a new location, and leave the original file unchanged.

Step 1: Select File > Save As.

Step 2: Specify a location, file format, and name.

Step 3: Click OK.

File types

Numerous file types can be selected when performing file level commands such as open or save.