diff --git a/HOWTO.adoc b/HOWTO.adoc index 26e1a8d..f8bea59 100644 --- a/HOWTO.adoc +++ b/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[]