Types of Topics

You can create different types of topics depending on your needs. For example, you might want to mimic DITA’s model, creating the following kinds of topics, even creating your own sub-categories:

  • Concept This is a topic that describes the meaning, background, and context for a subject. These are often “landing” topics, which usually provide links or navigation to related topics.
  • Reference This is a topic that is designed to store detailed reference information, often in one or more tables.
  • Task This is a topic that provides steps for completing procedures.
  • Troubleshooting This is a topic that explains why a certain issue occurs and how to correct it.

Standards and Structure

It is a good idea to set internal standards and design a basic structure for each type of topic you need to use. For example, your team might determine that each task topic should include the following elements, in order and perhaps written in a particular way:

  • Heading
  • Summary Paragraph(s)
  • Task Heading
  • Steps
  • Tips
  • Notes

Using topic templates is a good way to ensure consistency when creating each of these types of topics. You can include a skeleton structure for each topic type, with dummy text that authors replace in new topics. See Templates.

You can also make a copy of an existing topic of the same type and then replace the content with new information. However, use caution when doing this because some information might be unique to the original topic (e.g., meta description, template page), and you need to adjust that information as well in new topics.

Naming

You might consider using certain standards when naming your topics to help organize and identify them. For example, you might begin topics with the words “Concept,” “Reference,” or “Task,” depending on its type (e.g., Concept-Dog-Overview.htm, Reference-Dog-Breeds.htm, Task-Training-Dogs.htm).

What the MadCap Documentation Team Does

Most of our topics can be classified as one of the following:

  • Concept
    • Major landing page
    • Minor landing page
    • General concept
  • Task
  • Reference
    • General reference
    • UI element
  • Troubleshooting

We have created templates, which are skeleton versions of each of our topic types. When creating new topics, these templates can be used by any author.