Topic types

Topics come in different types. This has a direct impact on what you can write and how you can write your content.

Overview

Each organization can make their own specific types of topics, building templates that determine the internal structure and the mandatory elements that should be used in the topic. However, a small set of standard types, that are accessible to everyone, cover most uses. Those are:
  • Tasks
  • Concepts
  • References

As modular writing develops, more standard types appear, but those three still are the ones you are the most likely to see and work with in Draft Space.

Custom types

A topic is made of many different elements that each has a specific function: title, paragraph, list, task step, prerequisites, table, etc. Therefore, depending on the specific application for the content, your organization could define:
  • Style sheets that make some elements mandatory or forbidden in topics.
  • Templates that will produce topics populated with specific elements.

For example, your organization could define a template that fills in new topics with a paragraph, a picture and a table, and make any other element forbidden. In this case, any writer must adapt the content to the allowed format, and in this case will not be allowed to create sections, tasks steps, or any elements other than the ones already in the new topic. Of course, style sheets and templates can also be much more flexible.

This is why when you create a topic, you need to know what type of topic you should select depending on what type of content you have to add. If you realize, after you have created the topic and started to write in it, that your content doesn't match the type, then there is no other solution than deleting this topic, and creating a new one with the correct type.

Standard types

A standard topic type is a topic type defined by the DITA standards. The three standard types that have the widest application range and the ones that you will the most probably encounter are: concepts, tasks and references. They can however be further specialized into either a specialized standard topic or a custom topic.
  • Concept: a concept topic is where you provide explanations of how things generally work. Those topics contain the theoretical side of your content. Concept are flexible, allowing tables, images, lists and so on. You can structure your content with sections inside a concept. However, you can only use one level of sections (a section cannot contain sections).
  • Task: a task topic is where you provide procedures and actions. Those topic classically follow concept topics as they describe the practical side of your content. The task is one of the most constrained type of topics: you can only list action steps, and optionally step choices and results. It still allows a context presentation at the start of the topic, and also a prerequisite list.

    A technical documentation is usually about how the user can perform actions, so the task topics tend to be the backbone of your document.

  • Reference: a reference topic is where you provide the complete lists of items for reference. Those topics are the dictionary part of your content, it can be a list of terms with definitions, a table of error codes, a list of compatible software... The reference is a flexible topic where you can structure your content as you like, with table, lists and other dividing structure such as the section or the "definition list" structure. When you start using one structure, however, you must stick with it in the entirety of the topic.