HOWTO.adoc - Specify Admonition Usage and Basic Formatting Rules (#29)

HOWTO.adoc

@@ -15,7 +15,8 @@ When writing a warning, note, or similar, use an active voice. Speak _to_ the re
 > Warning: Doing `this` will give you weird results. You should try to do `that` instead.
 
 === Abbreviations
-When writing in _plain English_, **avoid abbreviations**. This also includes things like "&" instead of "and" and "@" instead of "at".
+When writing in _plain English_, **avoid abbreviations**.
+This also includes things like "&" instead of "and" and "@" instead of "at".
 
 When writing _code examples_, **label abbreviations sufficiently**, either by self-labeling (match the abbreviation to the value) or with a comment.
 
@@ -35,18 +36,38 @@ 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.
+This is software documentation, so technical explanations are expected.
+But it is important to know when and how much to explain technical things.
 
 === Object Names
 When referring to an object, use it's full name, the accepted shorthand, or it's highest generic term.
 
-For example: An `ItemStack` should be referred to as "ItemStack", "stack", or "object", depending on the need. It should _not_ be referred to as "userdata" or "reference". Objects that have metatables should usually _not_ be referred to as "metatable".
+For example: An `ItemStack` should be referred to as "ItemStack", "stack", or "object", depending on the need.
+It should _not_ be referred to as "userdata" or "reference".
+Objects that have metatables should usually _not_ be referred to as "metatable".
 
 === Technical Jargon Saturation
 Avoid too much technical detail for things that are unimportant, implied, or explained soon after.
@@ -61,14 +82,26 @@ GOOD:
 
 > The `ThisObject` object is a helper for handling `ThatObject` objects.
 
-All we need to know is that it helps us handle `ThatObject`. What it actually does should be documented afterwards.
+All we need to know is that it helps us handle `ThatObject`.
+What it actually does should be documented afterwards.
 
 === Internal Implementations
-In general, describing internal implementations is unnecessary and confusing. Avoid it unless absolutely essential for understanding something.
+In general, describing internal implementations is unnecessary and confusing.
+Avoid it unless absolutely essential for understanding something.
 
-This applies to meta implementations as well. For example, given the constructor `YourObject()`, do not document it as `YourObject.new(self, o)`. When describing the constructor, say "Creates and returns a new `YourObject` ". Do not go into unnecessary detail about what it does under the hood, such as `__index` management.
+This applies to meta implementations as well.
+For example, given the constructor `YourObject()`, do not document it as `YourObject.new(self, o)`.
+When describing the constructor, say "Creates and returns a new `YourObject` ".
+Do not go into unnecessary detail about what it does under the hood, such as `__index` management.
 
 == Format
+Noteworthy rules include:
+
+* Use one sentence per line
+* Define macros for long URLs, or those used multiple times
+* Use delimitated example blocks for examples, but not for general function usage
+* Long-winded tables should generally use one cell per line
+
 See link:templates/standard.adoc[standard template] for an example.
 
 === Includes
@@ -110,10 +143,12 @@ All types should link somewhere at some point (cross-reference or outside).
  
  .Example title
  ====
+
  [source,lua]
  ----
  -- Example code
  ----
+
  ====
 ----
 
@@ -121,7 +156,7 @@ All types should link somewhere at some point (cross-reference or outside).
 ----
 * `property_name:` `type`
 * `another_property:` `type`
- ** A description.
+** A description.
 ----
 
 include::include/footer.adoc[]