Technical Documentation from the Inside: Key Structural Elements

In this session, Ekaterina explored the fundamentals of content structural models, their purpose, and how they can transform your documentation from a cost center into a competitive advantage.

She delved into three leading models—DITA, Diátaxis, and the Simplified Content Model, covering their core components, content structures, typical use cases, and considerations.

Key Takeaways from the Session

Ekaterina provided a comprehensive breakdown of the three models, emphasizing their role in designing, organizing, and scaling documentation.

Here’s a summary of the core concepts:

1. DITA (Darwin Information Typing Architecture)

• Overview: A topic-based, XML-driven model maintained by OASIS since 2004. Ideal for complex, multi-role, or multi-platform products.
• Core Components: Topics include Concept (explanations of subjects), Task (step-by-step instructions), Reference (supplementary data like APIs), Glossary, and Troubleshooting.
• Content Structure: Builds high-level docs like user guides, with sections aligned to topics (e.g., overviews as Concepts, procedures as Tasks).
• Use Cases: Reusing content for role-specific guides (e.g., admins vs. end-users), platform variations (on-premise vs. cloud), or aggregated docs (e.g., licensing policies).
• Considerations: Excellent for consistency and single-source publishing but requires specialized software and knowledge. Beginners can adopt the structure without the full spec.

2. Diátaxis

• Overview: A content-structure-only model developed by Daniele Procida since 2017. Focuses on user intent without strict specifications.
• Core Components: Tutorials (step-by-step learning), How-To Guides (goal-oriented tasks), Explanations (subject matter overviews), and Reference (low-level details).
• Content Structure: Creates user guides with sections like Getting Started (Tutorials), Procedures (How-Tos), and Overviews (Explanations). Glossaries and FAQs are supplementary.
• Use Cases: Best for single-product docs with low content overlap, such as small-to-medium software products (e.g., Divio or Wagtail CMS).
• Considerations: Simple and beginner-friendly; requires third-party tools for reuse. Great for readability and logical flow.

3. Simplified Content Model

• Overview: A newer, topic-based concept emphasizing essential elements (developed by Ekaterina). Platform-independent and focused on user actions.
• Core Components: Information (passive content like concepts, references, FAQs) and Procedure (action-required content like tutorials, how-tos, troubleshooting).
• Content Structure: Entire docs built from these topics, without fixed high-level types like user guides. Flexible for any product complexity.
• Use Cases: Versatile for single products, suites, or aggregated docs; adaptable to any scenario.
• Considerations: Extremely simple for beginners but needs refinement with layouts and examples. Requires external tools for reuse.

About the Speaker

Ekaterina Noskova is a technical writer with 9+ years of experience. During her professional journey, she created software documentation for developers and engineers, built documentation and localization processes in an Agile environment, and managed the team of talented technical writers, UX writers, and DocOps engineers. She is keen on technical writing advocacy and actively mentors technical writers as well as other specialists who want to improve their technical writing skills or get recommendations about professional development and improving documentation processes.