Expand errata authoring docs

Author: kfranqueiro

errata/README.md

@@ -30,14 +30,45 @@ The level 2 heading in the top-level section for each previous version should us
 ## Erratum format
 
 Each erratum should be in the following format
-(replacing `YYYY-MM-DD`, `Section Title`, and `details of what happened`):
+(replacing `YYYY-MM-DD`, `Section Title`, `details of changes`, and `#NNNN`):
 
 ```html
-<li>YYYY-MM-DD: In <a href="{{ trUrl }}#sectionid">Section Title</a>, details of what happened.</li>
+<li>
+  YYYY-MM-DD:
+  In <a href="{{ trUrl }}#sectionid">Section Title</a>,
+  details of changes.
+  ({% gh #NNNN %})
+</li>
 ```
 
 Adhering to this format is important, as any entries under the latest published version will also be
 parsed for inclusion within Guideline/SC boxes and Key Terms definitions within Understanding pages.
+(Newlines are insignificant and are suggested for source code readability.)
+
+Each piece of this format is further explained in the subsections below.
+
+### Section reference
+
+When applicable, errata should begin with an indication of the section they relate to, including a link.
+
+Example phrasing when linking to a section, e.g. a success criterion:
+
+```html
+In <a href="{{ trUrl }}#target-size-minimum">2.5.8 Target Size (Minimum)</a>
+```
+
+Example phrasing when linking to a term definition:
+
+```html
+In the definition for <a href="{{ trUrl }}#dfn-single-pointer">single pointer</a>
+```
+
+(Remember that term definition fraagments always begin with `dfn-`.)
+
+It is possible to reference multiple sections/terms from one erratum,
+so long as all of the links remain front-loaded prior to the erratum's details.
+
+### Details of changes
 
 `details of what happened` should be expressed in present progressive tense
 (e.g. "updating", "removing", "adding"), with the desired outcome listed first.
@@ -47,3 +78,16 @@ For example:
 - removing one note and adding two new notes, including ...
 - removing a supernumary "Note" indicator from the first note.
 - correcting the word ... to ...
+
+### GitHub PR or commit
+
+When possible, provide a reference to one or more GitHub pull requests or commit hashes
+at the end of each erratum, in the format `({% gh "..." %})`.
+
+The format breaks down as follows:
+
+- `{% gh "..." %}` is a custom shortcode, which accepts one of the following:
+  - A PR number prefixed with `#`, e.g. `"#4080"` (this is the preferred option when available)
+  - A commit hash of 7 or more characters, with no prefix, e.g. `"b043430"`
+- The quotes around the parameter passed to the `gh` shortcode are necessary for template parsing
+- The outer parentheses exist only for punctuation, and are directly output