DocBook has a set of block-level tags called admonitions. Admonitions are used to call attention to specific pieces of information, usually by displaying them as distinct blocks in different colours. DocBook has five admonitions (NOTE, IMPORTANT, TIP, CAUTION, and WARNING).
The NOTE, IMPORTANT and WARNING admonitions are the most commonly used. Publican does not support TIP and CAUTION, considering them adequately covered by NOTE and WARNING. Examples of what these look like in Publican can be seen in the Document Conventions section of any document built using Publican and any of the standard brands.
In my opinion, the use of admonitions leads to inferior document design and a poor reading experience. Admonitions “call attention to specific information” and to achieve this aim they are formatted to seize the reader’s attention. This creates distractions for the reader and clutters documentation with material that is unnecessary or at best misplaced. With the exception of WARNING, the information that each admonition represents can almost always be incorporated in a more usable (and maintainable) fashion.
To demonstrate this, I will discuss the three admonitions used by Publican. I will cover their purpose and how you can structure your documentation to present the same information in a clearer fashion.
The Publican document conventions describes NOTE as follows:
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
NOTE is described as containing non-essential albeit interesting information about the subject at hand. This is counter-intuitive. Why do you want to draw attention to non-essential information? Remember Strunk & White’s Rule #17: “Omit Needless words”? The same principle applies to the document. Omit needless content. If content can be removed with no negative consequence then it should be. If the content is required to be included then at the very least it should be removed into a footnote, or an appendix. Unnecessary information should not be included in the main flow of the document.
Again I refer to the Publican document conventions:
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration.
The IMPORTANT admonition seems to make a great deal of sense, highlighting information that readers often miss or steps that they skip over. However it is not the best solution to this problem.
The problem is that readers sometimes miss important information or skip over procedure steps. Sometimes this is accidental, and sometimes a reader intentionally skips a step, intending to come back later and forgetting to do so. There isn’t much point in trying to figure out which steps are likely to be skipped or forgotten because you don’t know the circumstances of the reader. If you do this, you will find yourself filling your procedures with unnecessary information that will make them more difficult to follow.
A cleaner solution is to put this additional information afterwards in a Troubleshooting section. When the reader encounters difficulties there will be one definitive place to look for help. This is easier for the reader, and is also easier for future writers to maintain. Keep your content as lean and as clear as possible. Only supply additional information at the point when it is required.
WARNING is the one admonition that I am in favour of in general use. The Publican document conventions defines WARNING with:
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
WARNING differs from IMPORTANT in that it is critical that the reader is aware of it before performing a task. The reader is unlikely get a second chance. WARNING is for those situations where mistakes or deviating from a procedure will cause unrecoverable failure.
WARNINGs should be placed before instructions so the reader is forewarned. Procedures that can fail in this fashion could be preceded with a WARNING detailing the risks. The specific risky steps may also require a WARNING as well but this may be overkill.
One edge case that favours admonitions
Although it is preferable to not use admonitions, I have to point out that there is one use case where the disadvantages of admonitions can be leveraged to the benefit of readers: the update of documents in time-critical situations.
When a document must be updated and made available as quickly as possible, admonitions can be easily used to insert new content that is delineated from the existing material and highly visible to readers with very little effort. However this technique must be acknowledged as a temporary solution. The work which must be done to correctly incorporate this new information is hinted at by the types of admonition that are used as discussed above.
Admonitions, with the exception of WARNING, should not be used as a standard part of documentation because they reduce usability. The information they encapsulate can always be presented in a clearer form that does not disrupt the reader. The WARNING admonition is different in that the information it presents is critical to the reader.
The one exception to this is time-critical updates to documents, where the ease of use of admonitions and their high visibility to the reader is advantageous.
Without admonitions as a crutch, documentation does require more forethought. However your readers (and future maintainers) will thank you.