This repository has been archived by the owner on Sep 24, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 171
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
initial base restructure ideas into new files.
- Loading branch information
Cameron Shorter
committed
Apr 23, 2021
1 parent
3c551e6
commit e576c80
Showing
4 changed files
with
156 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
<!--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 file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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}. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|