Add optional revision-history and decision-log sections to base-template

base/base-guide.md

@@ -1,6 +1,6 @@
 # {Doctype} guide
 
-This {doctype}-guide provides extra writing tips for each of the sections within the {doctype}-template.
+This {doctype}-guide provides extra writing tips describing **HOW** to fill in each of the sections within the {doctype}-template.
 
 **Version:** {MAJOR.MINOR.PATCH}
 
@@ -15,11 +15,13 @@ To make the best use of this guide, it helps if you have a working knowledge of:
 
 ## {Doctype} content
 ### Hero description
-The hero description stands alone, just under the title. It is sometimes referred to as the "TL;DR statement", short for: Too Long; Dont Read" and is written as:
+The hero description stands alone, just under the title. It is sometimes referred to as the "TL;DR statement", short for: Too Long; Dont Read" and is sometimes written as:
 ```
    TL;DR: {Hero description.}
 ```
 
+We recommend against including the "TL;DR" acronym as some readers might not be familiar with it.
+
 It should be very short so that a reader will naturally want to read it. Its purpose is to quickly help the reader decide whether they should read any further.
 
 It should concisely explain what this document covers, and the type of person who will be interested in reading it. 
@@ -115,18 +117,10 @@ _(TBD: Discuss/improve recommendations for [schema.org](https://schema.org/) met
 
 ## {Sections and subsections}
 
-
 * Include standard headings applicable for this template’s `doctype`.
 * Where applicable, provide standard text for relevant sections.
 * Include tips for doc authors.
-* Some sections will be optional and include an "optional" tip to the doc author.
-}
-
-{Doc author tip:
-
-* Optionally include this section if {some condition}.
-
-}
+* Some sections will be optional and so should include the "optional" tip to the doc author.
 
 ## What’s next
 
@@ -145,6 +139,20 @@ This section is optional.
 
 }
 
+## Revision history
+
+This section is optional, and typically should not be included.
+
+It is typically only include for formal or impportant documents where readers are likely to be interested in the document's change history. 
+
+It typically should only list major, public facing updates.
+
+## Decision log
+
+This section is optional, and typically should not be included, or should be included in an accompanying document.
+
+It is typically only included for business process documents where readers may challenge the reasoning behind a decision.
+
 ## Acknowledgements
 
 * This section is optional.

base/base-template.md

@@ -2,7 +2,7 @@
 
 {Tip:
 
-* This {doctype}-template captures the structure and common text that should be included in all {doctype} documents.
+* This `{doctype}-template` captures the structure and common text that should be included in a `{doctype}` document.
 * It includes tips (such as this) and variables inside curly brackets. These tips and variables should be replaced or removed from the final document.
 
 }
@@ -54,6 +54,7 @@ It is designed to help {persona or personas} to achieve/learn {some goal}.
 
 {Tip:
 
+* Optionally include this section if {some condition}.
 * {Section specific tip 1.}
 * {Section specific tip 2.}
 
@@ -63,6 +64,7 @@ It is designed to help {persona or personas} to achieve/learn {some goal}.
 
 {Tip:
 
+* Optionally include this section if {some condition}.
 * {Subsection specific tip 1.}
 * {Subsection specific tip 2.}
 
@@ -75,9 +77,39 @@ Refer to:
 * {[Some doc title](https://example.com/somedoc.html) for {similar concepts}.}
 * {[Some doc title](https://example.com/somedoc.html) for {background theory}.}
 
+## Revision history
+
+{Tip:
+* This section is optional or can be combined with the ```decision log``` section if needed.
+
+}
+
+The following table describes the history of {all/major} decisions and revisions made to this {document} over time. 
+
+This guide uses the Major.Minor.Patch [semantic versioning](https://semver.org/) convention.
+
+Edition  |  Date          |  Lead Author(s)    |  Link to Repository Commit/Tag
+-------  |  ----          |  --------------    |  -----------------------------
+0.2    |  {YYYY-MM-DD}  |  {Your name here}  |  Customised for this project's needs
+0.1    |  {YYYY-MM-DD}  |  {Your name here}  |  Initial [{doctype}-template {version}](https://github.com/thegooddocsproject/templates/tree/main/{doctype}) from The Good Docs Project.
+
+
+## Decision log
+
+{Tip:
+* This section is optional or can be combined with the ```revision history``` section if needed.
+
+}
+
+The following table describes the history of all decisions made to this {document} over time:
+
+Ref  |  Date         |  Description                               |  Agreed to by
+---  |  ----         |  -----------                               |  ------------
+1    | {YYYY-MM-DD}  |  {Explain the decision that was made here} |  {Name or role}
+
 ## Acknowledgements
 
 This document draws inspiration from:
 
 * [The Good Docs Project](https://thegooddocsproject.dev) templates, version {MAJOR.MINOR.PATH}.
-* ...
+* {...}