Callout decision guide

The question it helps answer

Use the callout decision guide to organise the reasoning behind this question: When should documentation use a note, tip, warning, prerequisite, or no callout? The working view makes callout types, user consequence, and severity visible so discussion can move from general opinion to a specific action or decision.

When to use it

Use the callout decision guide when people working on documentation and naming are using different mental models for callout types, user consequence, and severity, and that difference is changing choices or coordination.

What it is

The callout decision guide is a set of connected concepts for examining one situation from several necessary angles. Its core working elements are callout types, user consequence, severity, and placement. Those elements belong together because each changes how the others should be interpreted or acted on.

Core elements

Callout types

Capture callout types only at the level needed to answer: When should documentation use a note, tip, warning, prerequisite, or no callout? Use observable evidence, name any unresolved judgment, and state what action or choice this entry can change. Within the callout decision guide, connect this entry to user consequence so the relationship can be reviewed rather than inferred.

User consequence

Identify the relevant people or groups, their needs, and any important differences in influence, access, or impact. Within the callout decision guide, connect this entry to severity so the relationship can be reviewed rather than inferred.

Severity

Capture severity only at the level needed to answer: When should documentation use a note, tip, warning, prerequisite, or no callout? Use observable evidence, name any unresolved judgment, and state what action or choice this entry can change. Within the callout decision guide, connect this entry to placement so the relationship can be reviewed rather than inferred.

Placement

Capture placement only at the level needed to answer: When should documentation use a note, tip, warning, prerequisite, or no callout? Use observable evidence, name any unresolved judgment, and state what action or choice this entry can change. Within the callout decision guide, connect this entry to wording so the relationship can be reviewed rather than inferred.

Wording

Capture wording only at the level needed to answer: When should documentation use a note, tip, warning, prerequisite, or no callout? Use observable evidence, name any unresolved judgment, and state what action or choice this entry can change. Within the callout decision guide, connect this entry to frequency so the relationship can be reviewed rather than inferred.

Frequency

Set a review rhythm and define the evidence, threshold, or event that should trigger an earlier review. Within the callout decision guide, connect this entry to anti-patterns so the relationship can be reviewed rather than inferred.

Anti-patterns

Capture anti-patterns only at the level needed to answer: When should documentation use a note, tip, warning, prerequisite, or no callout? Use observable evidence, name any unresolved judgment, and state what action or choice this entry can change. Within the callout decision guide, connect this entry to frequency so the relationship can be reviewed rather than inferred.