Case Study: Documentation Structure Redesign

Redesigning Documentation Structure to Separate Concepts from Tasks

Situation

  • DITA documentation with concepts embedded in task topics

  • Tasks were long and difficult to scan

  • Writers lacked guidance on where conceptual information belonged

Problem

  • Tasks tried to explain what and why in addition to how

  • Readers struggled to find actionable steps

  • Maintenance required updating the same explanations in multiple tasks

Architectural Approach

  • Reviewed task topics to identify conceptual overload

  • Defined clearer topic boundaries between concepts and tasks

  • Redesigned the topic structure so conceptual information had a proper home

Key Decisions

  • Move conceptual explanations out of task topics

  • Keep tasks focused on user actions

  • Establish consistent patterns for referencing concepts from tasks

Results

  • Shorter, clearer task topics

  • Improved scannability

  • Reduced duplication of conceptual content

  • Easier maintenance when concepts changed

Why This Matters

Clear topic boundaries improve usability and reduce maintenance effort without requiring wholesale rewriting of content.