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:
Consider the following example.
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.
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.
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:
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.
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:
That's it. A very generic sample. In XML it may be this:
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.
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:
The code for it may look like the following:
The task may have a very brief shortdesc to support the title as seen here:
A second task may be required to distinguish between the traditional Save option and the Save As option.
The reference may appear as seen here:
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:
Of course, there is no promise that any or all of this content will ever be published together, so it is of great importance to ensure that the message is always clear, always concise, and always written to the best of your abilities.
In this example it is easy to see a sample of the output, and the value of consistent phrasing. The message is clear, the finished topic concise, and DITA best practices are followed.