Difference between revisions of "Documentation Primer/Manual/DocBook Reference/Tips"

Latest revision as of 11:35, 9 September 2012

Other languages:

English

[edit] Admonitions: Tips, hints, and Warnings

Admonitions are set off from the main body of the text. Use these sparingly, as they disturb the flow of the writing, but don't be afraid to use them where necessary. Just make sure they are necessary when you do use them.

We have settled on a preliminary order of importance for these elements, which differs from that explained in the Duck Book. Note that this particular order is for KDE Documentation only, and use your own judgement which is the most appropriate element if your situation differs from those outlined.

<warning>

Use warning when data loss could occur if you follow the procedure being described.

<caution>

A note of caution. Use this for example when the reader may lose easily recovered or replaceable information (e.g. user settings), or when they could cause data loss if they don't correctly follow the procedure being outlined.

<important>

When there is no danger of data loss, but you wish to make clear to the reader a consequence that isn't immediately obvious (e.g. when changing the font for one instance of a program also changes the default setting, and this isn't clear from the GUI.)

<note>

Information the user should be aware of, but is peripheral to the actual task being described.

<tip>

When you're giving a hint to make things easier or more productive for the reader.

<footnote id="">

Use very sparingly for things that really are footnotes. An example might be to note that the situation being described will be changing at some currently unknown future time. Most footnotes would better be marked up as notes, or tips.

<footnoteref linkend="">

You can refer to a footnote more than once, by using this element to refer to it's unique id. The footnote does not need to be in the same chapter. Use this very sparingly.

• ← General markup
• ↑ Back to Menu ↑
• The synopsis elements →