Interim restructuring into template/guide/theory and then some

base/base-checklist.md

@@ -0,0 +1,15 @@
+# {Doctype} checklist
+{
+Tip:
+
+* Before writing your {doctype} document, you should plan to address all items on the following checklist. Before finalizing, you should check they are complete.
+
+}
+
+* [ ] The document has been reviewed:
+    * [ ] For clear writing and alignment with the writing style guide, ideally by a technical writer or editor.
+    * [ ] For alignment with the {doctype} template, ideally by a technical writer, information architect, or content strategist.
+    * [ ] For technical accuracy, ideally by a technical subject matter expert.
+* [ ] {Further doctype specific checklist items ... .}
+
+_TBD: See also: [the documentation maturity checklist](https://github.com/google/opendocs/blob/main/audit/checklist.md)_.

base/base-docset-owner-guide.md

@@ -0,0 +1,44 @@
+# {Doctype} customization guide
+
+This guide describes a {doctype} document's:
+* Unique characteristics,
+* When to include the {doctype} dotype in a project's documentation set, and
+* How [{doctype} template-set templates](../{doctype}) should be customized by a docset-owner to address a project's needs.
+
+
+**Version:** {This document's version, in MAJOR.MINOR.PATCH format}
+
+**Last updated:** {Date in the format: *Month DD, _YYYY* or *Month, YYYY*}
+
+## base-template customization
+
+TBD: Explain the unique characteristics of this section.
+
+## base-example
+
+The {doctype}-example.md document should describe the fictional [chronologue](https://github.com/thegooddocsproject/chronologue/) project.
+
+We've chosen to use a common example project to reduce cognitive load on the reader, and to help build a common theme between templates.
+
+A fictional project was chosen over a real example because:
+* The fictional project's characteristics can remain static over time, ensuring examples don't need to be updated.
+* Characteristics can be invented to illustrate a specific feature.
+* We avoid having the select a "favorite" exemplar project, and upsetting non-selected projects. 
+* Examples and features can be a little whimsical, adding a little entertainment to the reading. Note, any whimsical additions should not come at the expense of legibility for the wide target audience.
+
+The `chronologue time machine` concept was chosen because:
+* It is obviously fake.
+* It is technical, and hence needs technical documentation.
+* It lends itself to adding some whimsical fun.
+
+## Best practices in writing examples
+
+_{TBD: Capture best practices in examples here. This will likely have multiple subheadings.}_
+
+
+## base-guide
+
+## base-checklist
+
+## base-theory
+

base/base-doctype-guide-template.md

@@ -50,7 +50,7 @@ Before writing your {doctype} document, you should plan to address all items on
     * [ ] For clear writing and alignment with the writing style guide, ideally by a technical writer or editor.
     * [ ] For alignment with the {doctype} template, ideally by a technical writer, information architect, or content strategist.
     * [ ] For technical accuracy, ideally by a technical subject matter expert.
-* [ ] {Further checklist items ... .}
+* [ ] {Further doctype specific checklist items ... .}
 
 ## User stories
 

base/base-guide.md

@@ -1,51 +1,103 @@
 # {Doctype} guide
 
-This {doctype}-guide describes the process an author should follow when creating a {doctype} document.
+{Tip:
 
-**Version:** {This document's version, in MAJOR.MINOR.PATCH format}
+* This guide includes tips (such as this) and variables inside curly brackets. These tips and variables should be replaced or removed from the final document.
 
-**Last updated:** {Date in the format: *Month DD, _YYYY* or *Month, YYYY*}
+}
 
-## Prerequisites
+This {doctype}-guide describes the **process** an author should follow when creating a {doctype} document and filling in the {doctype}-template.
 
-To make the best use of this guide, it helps if you have a working knowledge of:
+**Version:** {MAJOR.MINOR.PATCH}
 
-* The project's documentation style guide.
-* Technical writing basics.
+**Last updated:** {Month DD, YYYY}
 
-{Tip:
 
-* Refer to the short [highlights from Google’s developer documentation style guide](https://developers.google.com/style/highlights) to quickly learn the essentials.
-* If you want more, [Google’s tech writer training](https://developers.google.com/tech-writing) material is freely available.
-}
+## Common fields
 
-## Front matter
+This section discusses the common fields typically included in doctypes.
 
-Front matter is the metadata stored at the top of each document.
+### Hero description
+The hero description is an opening paragraph which stands alone, just under the title. It's purpose is to quickly help the reader decide whether they should read any further.
 
-{Tip:
+It should concisely explain what this document covers, and the type of person who will be interested in reading it. It should be limited to one to three short sentences.
 
-* All technical documentation should include [machine readable structured metadata](https://developers.google.com/search/docs/guides/sd-policies) which reflects the content in the page. Structured metadata helps search engines index pages appropriately, and facilitates content reuse. For instance, a page's description and associated image may be included in a search result for the page.
-* Within this project we have adopted the [JSON-LD](http://json-ld.org/) format for structured metadata, [as recommended by Google](https://developers.google.com/search/docs/guides/intro-structured-data).
-* Metadata fields listed as "must" and "should" for "starter" projects the `doctype-guide-template` table must be included in the schema.org metadata below. Other metadata fields should not be included in the `doctype-template`. A docset-owner may add or remove metadata fields when customizing the `doctype-template` for their specific project.
-* Refer to the `main-doctype-author-guide` for a deeper discussion about metadata.
+### Document version
+To enable consistency and traceability between cross-referenced documentation and software, all documentation should be versioned.
 
-}
+A versioning convention should be adopted, such as the widely adopted [semantic versioning](https://semver.org/) MAJOR.MINOR.PATCH format}.
+
+### Last updated
+
+The ```last updated``` field refers to the documentation's publication date. Follow the date naming convention from your project's style guide, such as [Google style guide's date guidance](https://developers.google.com/style/dates-times) which recommends long form description of date: ```Month DD, YYYY``` or ```Month, YYYY```.
+
+If adopting the short hand formatting, select the universal date format: ```YYYY-MM-DD``` or ```YYYY-MM```.
+
+### Indicative reading time
+
+Reading speed usually should not be included in fields. There are two lines of thought around including a ```reading time``` field.
+
+Pros:
+* It helps someone decide whether they have time to read the page.
+
+Cons:
+* It is hard to account for:
+    * The range of technial expertise and reading speeds of readers.
+    * The varying technical complexity of source material.
+    * Multiple authors applying differing rules to assess reading time.
+* It potentially makes slow readers feel inadequate and demotivated.
+* Reading time is less appicable for some doctypes.
+
+Guidelines for calculating reading time:
+* Base estimates on the least experienced and slowest target reader.
+* Typically assume a reading speed of 50 words per minute for technical material, and 200 words per typical business material. [ExecuRead reading speed source assessment](https://secure.execuread.com/facts/#:~:text=The%20average%20reading%20speed%20is,roughly%202%20minutes%20per%20page.).
+
+_TBD: Provide better researched references and theory to this._
+
+### Application version(s)
+The documentation should list the version, or range of versions, of the application(s) this documentation describes.
 
-## Machine readable matadata
+### Metadata
 
-TBD: Talk about value of metadata. 
+All templates should include metadata, presented in visible form. Ideally, your documentation will include metadata embedded in machine readable [JSON-LD](http://json-ld.org/) format, such as:
 
 ```javascript
 <!--Machine readable schema.org structured metadata about this document.-->
 <script type="application/ld+json">
 {
   "name": "{Title of the document}",
   "description": "{Copy of the summary text}",
-  "version": "{This document's version, ideally in MAJOR.MINOR.PATCH format}"
-  "datePublished": "{Date in the format of YYYY-MM-DD or YYYY-MM}",
+  "version": "{MAJOR.MINOR.PATCH}"
+  "datePublished": "{Month DD, YYYY}",
   "license": "{URL to license}",
-  "audience": "{persona you are writing for, such as: developer, business manager, …}"
+  "audience": "{Persona you are writing for, such as: developer, business manager, …}"
 }
 </script>
-```
+```
+
+The metadata fields which should be presented by a document depends upon:
+* The value the metadata field provides to the target audience for the doctype.
+* The project's capacity to collect and maintain the metadata field. Can it be collected automatically?
+* The maturity and quality criteria set for the project.
+
+**Note:** Be careful not to overcommit to the number of metadata fields you introduce into your project's documentation:
+* Many metadata fields need to be maintained manually which adds a maintenance burden to the project.
+* If any of the metadata on a site is inaccurate or dated, it will reduce the trustworthiness of all content on the site, as the user typically won’t be able to determine which of the content is trustworthy.
+* As such, a project should only adopt metadata fields which are automatically maintained by your documentation publishing system, or where there is an established, low-effort process to ensure the metadata is maintained.
+
+Use the following table to help select the metadata fields to include in your {doctype} template:
+
+|Metadata field    |schema.org name|Typical location in doc         |Priority - startup|Priority - mature|
+|:-----------------|:--------------|:-------------------------------|:-----------------|:----------------|
+|Title             |name           |\<title> and \<h1> heading      |Must              |Must             |
+|Description       |description    |First paragraph summary         |Must              |Must             |
+|Doc version       |version        |Front metadata list             |May               |Should           |
+|Doc publish date  |datePublished  |Front metadata list             |Must              |Must             |
+|Reading time      |-              |Front metadata list             |May               |May              |
+|Target app version|-              |Front metadata list or Footer   |May               |Should           |
+|License           |license        |Footer                          |Should            |Must             |
+|Target audience   |audience       |Within first paragraph summary  |May               |Should           |
+
+**Note:** The terms "Must”, "Should”, and "May” should be interpreted as per [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+_(TBD: Discuss/improve recommendations for [schema.org](https://schema.org/) metadata fields. The table above should cover all metadata fields we consider should be recommended in the The Good Docs Project.}_

base/base-template.md

@@ -46,7 +46,7 @@ It is designed to help {persona or personas} to achieve/learn {some goal}.
 {Tip:
 
 * This section is optional.
-* You should include three to five links to more information.
+* You should include one to four links to more information.
 * Links should be a logical next step to what has already been read.
 * It will typically include a combination of related documents of this `doctype`, as well as relevant other `doctypes`. For instance, a tutorial may point to the next tutorial in a series, relevant reference material, and background conceptual theory.
 
@@ -57,7 +57,7 @@ It is designed to help {persona or personas} to achieve/learn {some goal}.
 {Tip:
 
 * This section is optional.
-* Here you can acknowledge organizations or people who have contributed to this document.
+* Here you can acknowledge source material, and organizations or people who have contributed to this document.
 
 }