Skip to main content

Types of documentation

Documentation should be organized based on user needs. The following is informed by the Diátaxis system.

Types of documentation​

  • Practice
    • Tutorials - Learning
    • Guides - Tasks
  • Theory
    • Reference - Information
    • Explanation - Understanding

Tutorials​

A tutorial is a practical activity, in which the student learns by doing something meaningful, towards some achievable goal.

The goal of a tutorial is to help beginners getting started. The focus is on learning and acquiring the competencies required to use the software. "Beginner" means anyone new to the topic at hand.

Provide step-by-step instructions. Each step should be easily attainable and provide concrete, meaningful results. The structure should be clear and linear. The tutorial should prepare the user for the rest of the documentation to continue learning.

  • Audience: Beginners
  • Purpose: Learning

Guides​

A how-to guide helps the user get something done, correctly and safely; it guides the user’s action.

A guide contains precise directions how to achieve a specific goal. In contrast to learning-oriented tutorials, a guide is a form of task-oriented documentation to solve a question that the user has.

It assumes some familiarity with the subject area, and unnecessary details can be omitted. The goal is not to give the full picture, but to focus on helping the user get to the goal.

  • Audience: Intermediate
  • Purpose: Problem-solving

Reference​

Reference material contains theoretical knowledge that a user looks to in their work.

This is the technical reference documentation that describes in detail how the entire software works. Typically this includes the API (application programming interface), as a library or service. The goal is to give comprehensive information that can be searched or read through to understand the internal mechanism. It should be dry, concise and to the point.

  • Audience: Experienced
  • Purpose: Information retrieval

Explanation​

Explanation deepens the reader’s understanding of a subject. It brings clarity and context.

This is a more detailed background material that clarifies the understanding of the software. For example, an in-depth overview of the design of a library, the thinking and logic that went into it. Also called background, discussion, or conceptual guides.

  • Audience: Experts
  • Purpose: Understanding