Which DITA topic type do I use when I'm not writing computer documentation?

Question

I'm a technical writer that is writing generic business process standards using DITA. I have selected DITA to use because of its excellent assembling of topics, content referencing and conditional profiling, all of which will help me control my complex, inter-related documentation.

I need to choose a topic type to use.

I have three options:

1. I can specialise my own topic type that meets my exact needs
2. I can use the topic topic.
3. I can use one or all of the OASIS computer documentation topics (concept/task/reference).

Option 1 is not realistic because I don't have access to DITA developers. Plus designing the specialization even as pseudocode is not trivial.

That leaves options 2 and 3 as realistic.

Option 2 has me using the topic topic. This gives me flexibility as it is the most forgiving topic type. It is also the most "clean" because I am not using topic types designed for something else. However the topic topic is really a base for specialization and is not supposed to be used directly.

Option 3 has me using the computer docs topics. I can more or less make my content fit them. However, they are really intended for "tripane help" type of content that it written in a specific kind of way. For example, these topic types are often used for writing according to John Carroll's minimalism, which encourages user experimentation and has a focus on the user's tasks. My kind of documents mandate requirements and I don't want to encourage minimalist principles in my writing.

Both options 2 and 3 involve compromise. Which is the better of the two for writing process standards?

Answer 1

Another option is to use the topic types provided by the DITA for Publishers project, which are intended to model typical non-tech-doc publication components: article, chapter, subsection, sidebar, and part.

The DITA for Publishers project is at http://dita4publishers.sourceforge.net.

Note that defining new topic types if you all you need is a distinguishing topic type tag name is trivially easy: it's entirely an exercise in copy and pasting and renaming and anyone can do it.

The configuration and specialization tutorials at http://www.xiruss.org/tutorials/dita-specialization/ walk you through it, although looking at them now I see that the topic specialization tutorial is actually more involved than just doing a simple root-tagname-only specialization.

Answer 2

The types concept, task and reference are not exclusively for computer documentation. I use these tasks also for

• text books
• guide for homebrewing of beer
• cooking recipes

For all these examples it was possible (not allways easy) to divide the content over the standard Dita types. Your term "Not computer documentation" is too vague. I think that when you tell more about your kind of content, many dita experts can advise you.

Answer 3

Although DITA was developed as a language for technical documentation, that is not the same as what I think you mean by computer documentation.

Use the Concept type to provide information that helps to orient users by contributing to their understanding of something. This could be as simple as "Why do I need to follow this SOP" or it could describe how some arcane algorithm works (if your user needs to understand that to perform a task correctly).

Use the Task type any time you describe how a user performs an activity. This need not be a numbered list of steps with "click this" and "type that" (although that is a frequent use case for software documentation). It can (and especially if you use the "general task" type) be more freeform if needed. The distinction here is that you are providing directions of some kind.

Use the Reference type to provide information your user might need to look up (usually to support an activity). If the topic is entirely a list or table, it's almost certainly reference information.

Experienced technical communicators may sometimes disagree about which topic type to use in a particular situation, but these are the general guidelines for distinguishing these three major topic types.

You can use generic topics if you like, but organizing information using a CTR (concept, task, reference) model has a proven track record of success in technical communications and would likely help your users even if the information is not of a technical nature. Think, for example, of a business presentation. It often starts with "what is the whoozy widget", continues with "how the whoozy widget will change your life" and concludes with links to purchase or get more information about the whoozy widget. CTR.

Answer 4

If you don't have access to developers, you could use DITA Generator to generate a simple specialization that only adds a new root element. Even if you don't create a structural specialization, you should still generate a custom shell DTD. This would allow you to use the base topic types like task, but not include e.g. programming and software domains if you don't need them.

Answer 5

There are many cases like this where one has to assess the benefits of DITA based on how strictly semantically tagged content is desirable while authoring so that the rendering comes out according to audience need. I think specialization is the only way to achieve higher levels of semantic tagging. For example, you might have a single specialized topic called requirement to start with. However, over time, you may have the need to further specialize the requirement element to other types such as hard-requirement, soft-requirement, mandatory-requirement, regulatory-requirement, functional-requirement, non-functional-requirement etc. Another consideration while deciding on the level of specialization is whether content tagged with this specialization needs to be consumed by any other system and if so, how closely aligned the semantics of both systems are and how the fall-back processing would work in the event that there is no matching element.

Not to deter anyone from trying but realistically, it takes a long time to develop comprehensive DITA specializations for certain domains. For the Semiconductor industry, a specialization called SIDSC is being developed since 2007 involving lots of companies and developers and it is still not widely used across the industry because of its complexity. However, as our products have tended to grow in complexity, our company's information developers are better able to keep up with documentation and publication challenges because we are using this specialization.

Answer 6

And you are not using concept, because of...?

In my experience is easy to say, that our customers use lots of concepts and even generic topics. This is indeed very common in several industries. I would say, that if your documentation is not instructional (tasks), just use concepts and then you don't have to specialize nothing.

But if some reason you need something very special, you should consider specialization. Just go to http://dita-generator-hrd.appspot.com/ and make it possible. :)