Admonition and issue use

The Asciidoc documentation gives guidance on how to write different types of semantic content. This section attempts to offer guidance on when to use specific elements.

Admonitions

The Asciidoc documentation does explain the difference between Caution and Warning. We expand on that, inspired by other documentation guidelines.

Neutral information

Use a NOTE to inform the reader of something even when skimming a page.

Positive consequences

Negative consequences

Use a TIP to help a reader benefit from potential added value, or to explore a new direction.
Use a CAUTION note to advise the reader to act carefully (i.e., exercise care), to avoid errors or mistakes.
Use an IMPORTANT note to share crucial information for the reader to be succesful.
Use a WARNING to inform the reader of danger, harm, or severe consequences that exist.

Feedback messages

Logging levels and feedback message types.

Type

Log level

Severity level

Meaning

Default

-

-

No specific meaning

Success

-

-

No problems encountered.

Critical

Fatal

Critical

Problem that prevents further operation and may result in other damage.

Danger

Error

Major

Problem that prevents further operation.

Warning

Warning

Minor

Potential problem but operation continues.

Note

Info

-

Relevant contextual information to monitor progress or results.

Tip

-

-

Possible improvement or additional information.

Diagnostic

Debug, trace

-

Detailed diagnostic information, usually aimed at developers.

Twitter LinkedIn Github Gitlab Meetup RSS Miro Trello Zotero Hypothesis