Documentation Types

Different documentation types serve different purposes. While structure and content focus vary, the tone of Product Documentation must remain consistent: calm, neutral, respectful, and direct.

Documentation type affects what information is included and how it is organized.

Reference Documentation

Reference documentation defines system behavior, parameters, limits, and technical specifications.

Reference content should:

• Present information in a strictly factual manner.
• Define behavior, inputs, outputs, and constraints clearly.
• Avoid narrative framing or explanatory storytelling.
• Avoid interpretation beyond what is necessary to understand the system.

Reference documentation should not:

• Include step-by-step procedures.
• Provide strategic recommendations.
• Include promotional or persuasive language.

How-To Guides

How-to guides help users complete a specific task.

How-to content should:

• Be procedural and action-oriented.
• Present steps in a clear, logical sequence.
• Focus on enabling task completion efficiently.

How-to guides should not:

• Include unnecessary background explanation.
• Mix conceptual discussion with procedural steps.
• Use motivational, encouraging, or promotional language.

Conceptual and Overview Pages

Conceptual and overview pages explain how systems work and how components relate to one another.

Conceptual content should:

• Provide context and clarify relationships.
• Explain principles, workflows, or architecture.
• Help readers understand why and how a system behaves as it does.

Conceptual pages should not:

• Include detailed procedural instructions.
• Provide exhaustive parameter definitions.
• Use marketing language or promise outcomes.

Errors, Warnings, and Notices

Error and warning content communicates important information about system behavior, limitations, or risks.

This content must:

• State the issue clearly and directly.
• Use calm, neutral language.
• Focus on facts and resolution steps where appropriate.

Error and warning content must not:

• Use urgent or emotionally charged language.
• Assign blame.
• Exaggerate risk or impact.