diff --git a/base/base-guide.md b/base/base-guide.md new file mode 100644 index 00000000..a1fbe00f --- /dev/null +++ b/base/base-guide.md @@ -0,0 +1,51 @@ +# {Doctype} guide + +This {doctype}-guide describes the process an author should follow when creating a {doctype} document. + +**Version:** {This document's version, in MAJOR.MINOR.PATCH format} + +**Last updated:** {Date in the format: *Month DD, _YYYY* or *Month, YYYY*} + +## 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. + +{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. +} + +## Front matter + +Front matter is the metadata stored at the top of each document. + +{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 matadata + +TBD: Talk about value of metadata. + +```javascript + + +``` \ No newline at end of file diff --git a/base/base-template.md b/base/base-template.md new file mode 100644 index 00000000..2a2035cd --- /dev/null +++ b/base/base-template.md @@ -0,0 +1,66 @@ +# {Doctype} template + +{Tip: + +* This {doctype}-structure template captures the structure and common text that should be included in all {doctype} documents. +* It includes tips (such as this) and variables inside curly brackets. These tips and variables should be replaced or removed from the final document. + +} + +{Tip: + +* The opening paragraph stands alone, just under the title. It's 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. +* It should be limited to one 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}. + +**This document version:** {This document's version, ideally in [semantic versioning](https://semver.org/) MAJOR.MINOR.PATCH format} + +**Last updated:** {Date in the format: "Month DD, _YYYY" or "Month 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.} + +{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 + +{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}. diff --git a/base/base-theory.md b/base/base-theory.md new file mode 100644 index 00000000..b36f11b0 --- /dev/null +++ b/base/base-theory.md @@ -0,0 +1,20 @@ +# {Doctype} theory + +{Tip: + +* "Template author tips" should be removed from the final xxx-template-guide. +} + +This "{doctype} theory document" provides reasoning, justifications, and links to research relevant to {doctype} documentation. It aims to empower authors to "think like a tech writer" and make documentation decisions backed by best practices. + +**Version:** {This document's version, in MAJOR.MINOR.PATCH format} + +**Last updated:** {Date in the format: "Month DD, _YYYY" or "Month YYYY"} + +## Checklist + +{Template author tip: + +* If there are unique extra doctype characteristics which should be included, add a checklist item for it in the checklist section of the `doctype` guide. + +} diff --git a/base/template-author-howto.md b/base/template-author-howto.md new file mode 100644 index 00000000..a31ce882 --- /dev/null +++ b/base/template-author-howto.md @@ -0,0 +1,19 @@ +# What's in the base-template directory + +How to create the doctype template files based on [The Good Docs Project](https://thegooddocsproject.dev) base-template docs. + +**Version:** 0.2 + +**Last updated:** April 2021 + +## Overview + +This document explains how to create the doctype template files based on [The Good Docs Project](https://thegooddocsproject.dev) base-template docs. It includes creating: + +* xxx-structure-template (what) +* xxx-example (what) +* xxx-guide-template (how) +* xxx-theory-template (why) + +## Prerequisites +