Moved incubator files into incubator/ dir

incubator/about-communications.md

@@ -0,0 +1,25 @@
+# The Overview
+
+## When Do I Need Communications Guidelines?
+
+Even the smallest projects need some kind of communications guidelines. Communications guidelines help users and contributors know how best to reach maintainers and help maintainers set expectations for users and contributors.
+
+
+## Content of Your Communications Guidelines
+
+### What Problems Does This Solve?
+
+Think about who is in your community and what kinds of questions they might have. Where should they go with their questions? When can they expect to get answers or responses? What should they do if they have an urgent problem or haven't received a response? This is the kind of information typically included in communications guidelines.
+
+Ideally, communications guidelines should reduce the amount of time maintainers spend managing questions and channels, by allowing users and contributors to manage themselves.
+
+
+### What Else Should I Consider?
+
+Typical information includes:
+
+* Instructions for joining discussion channels, such as Slack or mailing lists
+* Tags that are used on StackOverflow or other Q&A sites
+* Links to specific kinds of communications templates (like issue  templates or security vulnerability reporting templates)
+* Explicit statements about community communications norms. For example, you may state that rude or unkind requests will be ignored or deleted without response, or that job postings are only allowed in one specific channel.
+

incubator/base-template/README.md

@@ -0,0 +1,28 @@
+# What's in the base-template directory
+
+This base-template directory contains templates and guides to be followed by a `doctype` template author. They can also be used by a project's docset owner to select and customize the project's templates.
+
+**Version:** 0.1
+
+**Last updated:** February, 2021
+
+## How to use the base-template files 
+As a doctype author, you will be responsible for creating three documents:
+
+**xxx-template:**
+* Based on the _base-doctype-template_.
+* The doctype's headings, standard text, and specific instructions for each section.
+
+**xxx-guide-template:**
+* Based on the _base-doctype-guide-template_.
+* General guidance and background theory related to the _doctype_.
+
+**xxx-example:**
+* Based on the _doctype-example-guide_.
+* An example implementation of the doctype, which explains our fake chronologue project.
+
+Guidance for filling out these documents are provided as _template author tips_ within the above documents, as well as in the holistic _main-doctype-author-guide_.
+
+## Contributing new templates
+
+We welcome contributions to The Good Docs Project. Refer to our [contribution page](https://thegooddocsproject.dev/contribute.html) for details.

incubator/base-template/base-doctype-guide-template.md

@@ -0,0 +1,220 @@
+# {Doctype} guide template
+
+{Template author tip:
+
+* This `doctype-guide-template` captures the structure and common elements that all xxx-guide-templates should follow.
+* "Template author tips" should be removed from the final xxx-template-guide.
+* You will need to view the raw markdown to see the machine readable metadata.
+}
+
+This {doctype}-guide provides writing tips and background theory to help docset owners and documentation authors create good {doctype} documents.
+
+<!--Machine readable schema.org structured metadata about this guide.-->
+<script type="application/ld+json">
+{
+    "name": "{Doctype} guide template",
+    "description": "This {doctype}-guide provides writing tips and background theory to help docset owners and documentation authors create good {doctype} documents.",
+    "version": "{This document's version, ideally in MAJOR.MINOR.PATCH format}"
+    "datePublished": "{Date in the format of YYYY-MM-DD or YYYY-MM}",
+    "license": "http://creativecommons.org/licenses/by/4.0/",
+    "audience": "{doctype} document author, docset owner"
+}
+</script>
+
+**Version:** {This document's version, ideally in MAJOR.MINOR.PATCH format}
+
+**Last updated:** {Date in the format of YYYY-MM-DD or YYYY-MM}
+
+## Prerequisites
+
+To make the best use of this guide, it helps if you have a working knowledge of:
+
+* The project's documentation style guide.
+* Technical writing basics.
+
+## Primary goal
+
+{Template author tip: Concisely state the primary purpose of this doctype, ideally in one or two short sentences.}
+
+## Checklist
+
+{Template author tip:
+
+* Add checklist items which are specific to this `doctype`.
+
+}
+
+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 checklist items ... .}
+
+## User stories
+
+{Template author tip:
+
+* You should document the key user stories that this template is likely to be used for.
+
+}
+
+When writing, it is important to understand who you are writing for, and ensure that you provide just the right amount of information to address their needs. The following user stories should help you achieve that.
+
+A {doctype} document aims to address the following user stories:
+
+* As a {user persona}, I want to {achieve a specific goal}, so that I can {achieve a larger business objective}.
+* ...
+
+_{TBD: We should link to a page we are yet to write helping people pick personas.}_
+
+## Nature of content
+
+{Template author tip: 
+
+* Discuss the nature of the content for this doctype.
+* Discuss what format will best express the nature of the content. For example, text only, or multi-media options such as diagrams, screenshots or video.
+* Discuss how the format you choose will impact maintenance. This can include human work-hours, as well as ongoing processes and infrastructure requirements.
+* Reference your style guide, which should have recommended guidelines for using multimedia, such as image size and video length.
+* For content with numerous items or steps, consider "chunking" content into sub-sections of 5-10 steps. It makes the information easier to read and remember, and gives the reader a sense of accomplishment after each chunk is completed. Chunking is recommended by major companies, such as Microsoft in its [writing style guide](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions#complex-procedures), and from the Nielsen Norman Group's [research on chunking and usability](https://www.nngroup.com/articles/short-term-memory-and-web-usability/).
+
+}
+
+### Priorities for each quality criteria
+
+* Each `doctype` addresses different use cases. It targets different user personas, with different needs.
+* As such, there are different weightings applied to quality characteristics for each `doctype`. Reference documentation needs to comprehensively address all the features in the latest version, but can tolerate lower quality writing. Tutorials likely need only cover a sample of use cases, for an older version of the software, but there is a greater need for writing quality.
+* The following table is used to help prioritize your time when writing for this {doctype} doctype.
+
+{Template author tip: Apply priorities to the table below.}
+
+This table lists the relative importance of the following quality criteria for {doctype} documents.
+
+|Quality criteria                                        |Priority to address                                                                |
+|:-------------------------------------------------------|:----------------------------------------------------------------------------------|
+|Currency: Alignment with the latest version of software.|{Select one of: Must, Should, Nice to have (May), Not Applicable (N/A), Should not}|
+|Currency: Alignment with a specified version of software.|                                                                                  |
+|Comprehensive: Covers every feature and use case.       |                                                                                   |
+|Well written: Unambiguous.                              |                                                                                   |
+|Well written: Concise, high information density.        |                                                                                   |
+|Well written: Aligns with writing style guide.          |                                                                                   |
+|Well written: Engaging, entertaining, draws the reader in.|                                                                                 |
+|Audience: Target a specific persona and user story. Simplifies documentation by assuming prerequisite knowledge of the audience.|           |
+|Audience: Targets a broad international, multicultural audience. Avoids slang, colloquialisms, pop cultural references or local references.||
+|Audience: Considers a non-English speaking audience. Uses simple English.|                                                                  |
+|Audience: Consider accessibility and disability in audiences.|                                                                              |
+|Audience: Consider diversity and inclusiveness in language chosen.|                                                                         |
+|Maintainability: Written to be easily translated.        |                                                                                  |
+|Maintainability: Uses timeless language with reduced need to update over time.|                                                             |
+|Maintainability: Has established processes for auditing and updating content.|                                                              |
+|Maintainability: Has a healthy, engaged community of contributors.|                                                                         |
+
+Note: The terms "Must”, "Should”, and "May” should be interpreted as per [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+_TBD: The quality criteria list requires review and refinement._
+* _Further reading: [Tom Johnson's article on Measuring Doc Quality](https://idratherbewriting.com/learnapidoc/docapis_measuring_impact.html)._
+* _Further reading: Daniel Beck's Doc Audit work. TBD: Get the public link for this._
+
+## Implementation strategy
+
+{Template author tip:
+
+* This section is optional.
+* In some cases there may be tips you can provide on how to create a specific `doctype`.
+
+}
+
+## Business case
+
+{Template author tip:
+
+* In this section, discuss strategies to calculate the cost of implementing this `doctype`. This may just be to reference the development strategy and maintenance strategy above.
+* Then suggest business goals and reasons why this doctype would help address these goals. Business goals might be:
+    * Increased developer efficiency.
+    * Faster onboarding for users and/or developers.
+    * Reduced support costs.
+* Consider the case where the docs are only partially maintained. Would it be better to have no documentation than incorrect or partially maintained documentation?
+
+}
+
+### When to include {doctype} docs?
+
+{Template author tip:
+
+* Add a summarized list of reasons for writing the `doctype`, based on the business case above. 
+
+}
+
+You should write {doctype} docs when:
+
+* {Reason 1.}
+* {Reason 2.}
+
+### When wouldn’t you include {doctype} docs?
+
+{Template author tip:
+
+* Add a summarized list of reasons for not including the `doctype`, based on the business case above. 
+
+}
+
+Don't write {doctype} docs if:
+
+* {Reason 1.}
+* {Reason 2.}
+
+## Customization
+
+{Template author tip:
+
+* There are often multiple approaches to consider when implementing a `doctype`.
+* In this section you should discuss different approaches that can be applied to this `doctype`, including logic and recommendations to help a docset owner select the best strategy for them.
+* Often there would be a light and more comprehensive version of this template. Immature projects may only have the capacity to maintain the light version. You should discuss how a project might mature their docs from light to comprehensive versions.
+
+_{TBD: Add further guidance and sample text here.}_
+
+_{TBD: We are encouraging docset owners to branch a template and then customize. This branched version now won't track latest updates to The Good Docs Project templates. A more sustainable approach would be to have an accompanying configuration file which supports section inclusion logic and variables. A future toolchain would need to be set up before we could introduce accompanying config files.}_
+
+* There are multiple approaches which can be taken to customize this template. These may depend upon:
+    * The maturity of your project.
+    * The size, interest, and skillsets of your contributor community.
+    * The documentation goals you have for the project.
+* This section discusses approaches you may take to customize this template to your project.
+
+{Template author tip:
+
+* {Add customization advice here. …}
+
+}
+
+## Maintenance strategy
+
+See also the maintenance strategy section of the `doctype_guide`.
+
+{Template author tip:
+
+* In this section, you should recommend strategies for maintaining `doctype` documentation. This could include:
+* Automated documentation generation from code.
+* Automated reports which highlight:
+    * When documentation is out of date with software.
+    * When documentation hasn’t been reviewed for a while.
+* Integrating documentation checklists into software deployment, build, and test processes.
+* This section can remain empty if there are no extra recommendations to add beyond general guidance in the `doctype_guide`.
+
+}
+
+## Backing research and further reading
+
+{Template author tip:
+
+It isn’t sufficient to simply define best practices for a `doctype`. You need to provide compelling evidence as to why this is the best approach. If there isn't any research, then say so, provide your own recommendations, and explain why you think they are the best approach.
+
+"Do the hard work to make it simple." [UK Open Government Design Principle](https://www.gov.uk/guidance/government-design-principles#do-the-hard-work-to-make-it-simple)
+
+This section should summarize competing approaches and explain why you took the chosen approach.
+* It might also suggest situations where a docset owner would select a different approach.
+* Authoritative sources should be provided to justify recommendations.
+* If this section becomes more than a page long, consider extracting out into a separate research paper and then reference the paper.
+
+}

incubator/base-template/base-doctype-template.md

@@ -0,0 +1,89 @@
+# {Doctype} template
+
+{Template author tip:
+
+* This base template captures the structure and common elements that all xxx-templates should follow.
+* "Template author tips” should be removed from the final xxx-template.md.
+* "Document author tips" and variables in {curly brackets} should remain.
+* Adjust other tips to align with the `doctype` you are writing for.
+
+}
+
+{Document author tip:
+
+* This {doctype} template captures the structure and common elements that all {doctype} documents should follow.
+* It includes tips (such as this) and variables inside curly brackets. These tips and variables must be replaced or removed from the final document.
+* The introduction should concisely explain what this document covers, and the type of person who will be interested in reading the document. It should ideally be limited to two to three short sentences.
+
+}
+
+This document {explains/covers/shows what/how to do something}.
+
+It is designed to help {persona or personas} to achieve/learn {some goal}.
+
+{Document author tip:
+
+* 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.
+
+}
+
+<!--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}",
+  "license": "{URL to license}",
+  "audience": "{persona you are writing for, such as: developer, business manager, …}"
+}
+</script>
+
+**This document version:** {This document's version, ideally in [semantic versioning](https://semver.org/) MAJOR.MINOR.PATCH format} 
+
+**Last updated:** {Date in the format of "Month DD, YYYY"}
+
+## {Sections and subsections}
+
+{Template author tip:
+
+* 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}.
+
+}
+
+## What’s next
+
+{Template author tip: Most `doctypes` should provide links to help a document author find related topics and next steps.}
+
+{Document author tip:
+
+* This section is optional.
+* You should include three to five 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.
+
+}
+
+## Acknowledgements
+
+{Document author tip:
+
+* This section is optional.
+* Here you can acknowledge organizations or people who have contributed to this document.
+
+}
+
+This document draws inspiration from:
+
+* [The Good Docs Project](https://thegooddocsproject.dev) templates, version {MAJOR.MINOR.PATH}.