From e1a16e80279839885e22133dd0991b2fb03365e1 Mon Sep 17 00:00:00 2001 From: benrob0329 Date: Fri, 14 Jan 2022 17:42:21 -0500 Subject: [PATCH] HOWTO.adoc - add section on admonitions --- HOWTO.adoc | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/HOWTO.adoc b/HOWTO.adoc index 26e1a8d..6186e91 100644 --- a/HOWTO.adoc +++ b/HOWTO.adoc @@ -35,10 +35,27 @@ local emin, emax = vm:read_from_map(p1, p2) -- Emerged minimum and maximum posit === Grammar and Punctuation * Always capitalize proper names and first letters in plain text. - ** Capitalization in quotation marks is not required and usually discouraged. The goal of quotation in documentation is to mirror _exactly_. +** Capitalization in quotation marks is not required and usually discouraged. The goal of quotation in documentation is to mirror _exactly_. * End all plain text with a period. This does not apply to code examples. * Use the Oxford (or serial) comma. It helps reduce confusion. +=== Admonitions +The use of Admonitions (`NOTE:`, `TIP:`, `IMPORTANT:`, `CAUTION:`, and `WARNING:`) are useful for bringing the reader's attention to a specific idea or statement. +The use of these should generally follow these situation guidelines: + + +NOTE: This information is noteworthy. You will find it insightful to understand something. + +TIP: This information is helpful. You will have an easier time doing something if you follow this. + +IMPORTANT: This information is important. You really should know this or you may fail to understand something. + +CAUTION: You should be careful with this, something bad might happen if you aren't. + +WARNING: Something bad will happen if you do this, or don't do this. The game will crash, kittens will die, data will be lost, etc. + +Use of Admonitions should be done when it is truly warranted. +Their over-use will add too much visual noise to the document, and may distract the reader away from the overall document text. == Technical Detail This is software documentation, so technical explanations are expected. But it is important to know when and how much to explain technical things.