Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Commit

Permalink
initial base restructure ideas into new files.
Browse files Browse the repository at this point in the history
  • Loading branch information
Cameron Shorter committed Apr 23, 2021
1 parent 3c551e6 commit e576c80
Show file tree
Hide file tree
Showing 4 changed files with 156 additions and 0 deletions.
51 changes: 51 additions & 0 deletions base/base-guide.md
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>
```
66 changes: 66 additions & 0 deletions base/base-template.md
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}.
20 changes: 20 additions & 0 deletions base/base-theory.md
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.

}
19 changes: 19 additions & 0 deletions base/template-author-howto.md
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

0 comments on commit e576c80

Please sign in to comment.