Search code examples
dita

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

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?

Solution

  • 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.