Information mapping

Information mapping helps authors organize content by its type to help readers find the information they need, and to set consistent expectations as readers move through different topics in the Documentation Portal. This method of developing and organizing content works well with DITA. While DITA provides a framework for building topics, information mapping organizes the content by type within that framework.

The Product Documentation team uses only the DITA Default Topic type. Within those topics, organize content based on one of the following information types:

Note: While these information types are most commonly applied to topics, we can also apply them to other content-delivery methods, such as video.

Best practice is to keep content segregated in different topics by information type. However, you might sometimes find it better to combine information types in a single topic, especially when there is not much content, and when separate topics would cause the user more confusion than help. The goal is not to be pedantic about structure, but to make a consistent and predictable experience for users.

As technical writers, we often think first about how to organize content in a written format. When planning your content, consider applying the structure of information types to other content delivery formats. For example, if you are using videos consider parsing the information by information type. For a short how-to video, you might start with an overview (concept), show the procedure (task), and follow with a link for more information (reference).

In written content, information types can be used at the topic or section level of granularity. For example, for a simple process you might have 1 topic with a concept section, a process section, and a few task sections. Complex processes (such as creating a feedback program) would requite separate topics to make the user's goals easier to complete.

Note: While the following sections refer to topics, you can apply the same structure to sections within a topic.

Concept

Restriction: We do not use this type at Medallia.

Concept topics describe something. They provide the information necessary to proceed to processes, tasks, and sometimes other concepts. For example, you might use a concept topic to:

  • Explain the difference between feeded and feedless surveys.
  • Describe the architecture of Medallia Experience Cloud.
  • Introduce the tools in Admin Suite.

Task

Tasks describe how to do something, usually in a series of numbered steps, and are focused on a very specific goal or outcome. For example:

  • Creating a tab and subtab in Admin Suite Reports.
  • Creating a Sandbox instance for testing.
  • Assigning a role to users.
  • Formatting an organization file for Auto Importer.

When creating task topics, always describe the goal associated with completing the task. If the task is part of a larger process, note that fact and link to the process topic.

Process

Restriction: We do not use this type at Medallia.

Process topics are similar to tasks, in that they describe how to do something. However, rather than provide specific step-by-step instructions for a single, specific task, processes list a group of tasks that must be completed to reach the desired goal. The following examples are good candidates for process topics:

  • Implementing Medallia Text Analytics
  • Localizing Experience Cloud
  • Creating a Responses report in Setup

As with tasks, describe the goal of the overall process before listing the tasks involved.

Processes are often a series of numbered steps, with each step corresponding to a specific task topic. For each step, summarize what is accomplished by that step, and link to the associated task.

Reference

Restriction: We do not use this type at Medallia.

Reference topics provide detailed information, often to support important tasks. For example:

  • List of parameters on a configuration screen
  • Glossary of terms
  • List of API calls
  • What's New topic
  • Release notes