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

Jump to: navigation, search
(Marked this version for translation)
 
(Corrected links)
 
(3 intermediate revisions by one user not shown)
Line 1: Line 1:
 +
<languages />
 
<translate>
 
<translate>
  
Line 61: Line 62:
 
<!--T:18-->
 
<!--T:18-->
 
{{Prevnext2
 
{{Prevnext2
| prevpage=Documentation Primer/Manual/DocBook Reference/General markup
+
| prevpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/General markup
 
| prevtext=General markup
 
| prevtext=General markup
| nextpage=Documentation Primer/Manual/DocBook Reference/Synopsis
+
| nextpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Synopsis
 
| nexttext=The synopsis elements
 
| nexttext=The synopsis elements
| index=Documentation Primer/Manual
+
| index=Special:myLanguage/Documentation Primer/Manual
 
| indextext=Back to Menu
 
| indextext=Back to Menu
 
}}
 
}}
  
 
</translate>
 
</translate>

Latest revision as of 11:35, 9 September 2012

Other languages:English 100%

[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.

This page was last modified on 9 September 2012, at 11:35. This page has been accessed 1,128 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal