Are there guidelines for transitioning between different topic types in a document?

Transitioning between DITA topic types within a single document is a structured approach to ensure that the content flows logically and effectively. DITA allows flexibility in combining various topic types, and knowing how to transition between them is crucial for creating coherent and reader-friendly documents.

Well-executed transitions between topic types involve understanding topic type usage, using clear headings, maintaining consistency, providing contextual transitions, using cross-references, and maintaining a logical flow of information.

Understand Topic Type Usage

Before transitioning between topic types, it’s essential to understand the purpose and characteristics of each topic type. DITA provides various topic types, such as concept, task, reference, glossary, and more. Each topic type has a specific role in conveying information.

Use Clear Headings

Start each new topic type with a clear and descriptive heading or title that signals the change in content type. This helps readers anticipate what to expect in the upcoming section.

Maintain Consistency

Keep a consistent structure within each topic type. For example, in a task topic, maintain a consistent format for all steps. Consistency aids readability and comprehension.

Provide Contextual Transitions

When transitioning between topic types, provide brief contextual information or a summary of the previous topic’s key points. This helps readers connect the different parts of the document.

Use Cross-References

If the content in one topic type refers to information in another part of the document, use cross-references to link them. Cross-references provide easy navigation for readers.

Maintain Logical Flow

Think about the logical flow of information and the reader’s journey through the document. Ensure that the transition between topic types aligns with the reader’s expected progression.

Example: Concept and Task Topics

Concept Topic (Introduction to the Software)

            <title>Introduction to Our Software</title>
            <p>Our software is a powerful tool designed to...</p>
            <p>It provides users with various features, including:</p>
                <li>Feature 1: Describe Feature 1.</li>
                <li>Feature 2: Explain Feature 2.</li>

Task Topic (Getting Started)

            <title>Getting Started with Our Software</title>
                    <cmd>1. Launch the Software</cmd>
                    <p>Open the software by double-clicking the icon on your desktop.</p>
                    <cmd>2. Log In</cmd>
                    <p>Enter your username and password to log in.</p>

In this example, the transition from the concept topic (introduction) to the task topic (getting started) is marked by a clear title change. The concept topic provides an overview of the software’s purpose and features, setting the context for the user. The task topic then guides the user through specific actions to get started.