Merge branch 'master' into patch-2

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
-> __ALL Pull-Requests require an associated [Issue](https://github.com/thegooddocsproject/templates/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) as documented in [How to contribute](https://github.com/thegooddocsproject/templates/blob/master/contribute.md#contributing).__
+> __ALL Pull-Requests require an associated [Issue](https://github.com/thegooddocsproject/templates/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) as documented in [How to contribute](https://github.com/thegooddocsproject/templates/blob/master/CONTRIBUTING.md#contributing).__
 
 ## Purpose / why
 
@@ -23,3 +23,4 @@
 * [ ] If template updates: do they align with [developers.google.com/style/](https://developers.google.com/style/)?
 * [ ] Did the PR receive at least one :+1: and no :-1: from core-maintainers?
 * [ ] On merging, did you complete the merge using [keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#manually-linking-a-pull-request-to-an-issue)?
+* [ ] On merging, did you add any applicable notes to a [draft release](https://github.com/thegooddocsproject/templates/releases) and link to this PR?

README.md

@@ -4,47 +4,60 @@ This repository contains best-practice templates to help build documentation for
 
 Here we provide tips for using these templates.
 
+
 ## Core documentation types
 
-The templates are categorised in line with standard [DITA](http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/technicalContent/dita-technicalContent-InformationTypes.html#dita_technicalContent_InformationTypes) documentation types:
+The templates are categorized into three documentation types:
 
-**Concept**: Describes how and why things work. 
-Concepts are normally written to help the reader understand a technology, prior to using it.
+**Concept**:
+Describes how and why something works.
+Concepts answer the question "what is it?".
+When readers read concepts, they are learning about a topic.
+Use concepts to help the reader understand a technology, before they start using it.
 
-**Task**: Gives specific instructions about how to get something done. 
-In practice, Tasks tend to have a specific goal and usually consist of a set of numbered steps that the reader can follow to achieve the goal.
+**Task**:
+Gives specific instructions about how to get something done.
+Tasks answer the question "how do I do it?".
+When readers read tasks, they are doing something.
+Tasks tend to have a specific goal and consist of a set of numbered steps that the reader can follow to achieve that goal.
 
-**Reference**: Contains structured information or specifications that users need to make a product work. 
+**Reference**:
+Contains structured information or specifications that users need to make a product work.
+Reference material answers the question "what else do I need to know?"
+When readers read references, they are fact-checking.
 Reference sections should comprehensively catalog data such as functions and their parameters, return codes and error messages.
+They are often presented as tables, bulleted lists, or sample scripts.
 
 Our templates follow these documentation types, and you should find that your information naturally fits into them as you write.
 
+
 ## How to use these templates
 
-We like to compare documentation types to aisles in a grocery store. 
-Each aisle includes related templates, which you can think of as ingredients. 
+We like to compare documentation types to aisles in a grocery store.
+Each aisle includes related templates, which you can think of as ingredients.
 Use these ingredients in documentation cookbooks to whip up docs for your readers.
 
-When writing your documentation, it helps to think about the following:
+When writing your documentation, it helps to think about:
 
 * Who are you writing for?
-* What will they be trying to accomplish when they read the documentation?
-* The information type. Is it a concept, a task or reference?
+* What will they be trying to do when they read the documentation?
+* What information are you providing? Is it a concept, a task, or reference?
+
 
 ## The templates
 
-Templates we currently offer:
-
-| Template name | Documentation type |
-| ---------------------- | ------- |
-API Project overview | Concept
-API Quickstart | Concept, Task
-API Reference | Reference
-Discussion | Concept
-How-to | Task
-Tutorial | Concept, Task
-General reference entry | Reference
-Logging reference | Reference
+Current templates:
+
+| Template name | Documentation type | Description |
+| ------------- | ------------------ | ----------- |
+| API Project overview | Concept | An overview of your API |
+| API Quickstart | Concept, Task | Simplest possible method of implementing your API |
+| API Reference | Reference | List of references related to your API |
+| Explanation | Concept | Longer document giving background or context to a topic |
+| How-to | Task | Short series of steps for a particular task |
+| Tutorial | Concept, Task | A training document for a product or topic |
+| General reference entry | Reference | Specific details about a particular topic |
+| Logging reference | Reference | Description of log pipelines |
 
 ## The cookbook
 

api-overview/about-overview.md

@@ -1,43 +1,43 @@
 # The overview
 
-## When do I need an overview?
+## When do I need an overview
 
-Your API documentation should include an overview document. This document tells potential users or buyers what they might want to know before adoption.
+Your API documentation should include an overview document. This document tells potential users or buyers what they might want to know before they buy.
 
-Many users install or plug into your service immediately because they are already familiar with it or someone else has decided that the team will use this solution. All of those people will go to your Quickstart, or will just get to work.
+Users can install or connect to your service if they are already familiar with it, or if someone else has decided that the team will use this solution. Those readers will go to your Quick Start Guide, or get straight to work.
 
-There are other groups, however, who need to assess your product in order to decide whether they want to use it. For example, managers responsible for a business decision or engineers responsible for a technical assessment of your product. People in these groups might decide to not adopt your product unless you provide an overview that answers their questions.
+Other readers need to assess your product to decide whether they want to use it. This includes managers responsible for a business decision, or engineers responsible for a technical assessment of your product. People in these groups might decide to not adopt your product unless you provide an overview that answers their questions.
 
 ## Content of your overview
 
-### Who is this overview for?
+### Who is this overview for
 
-* Are you writing only for developers? For managers?
-* Are you writing only for people who have a certain problem to solve?
-* Is it intended for a particular industry.
+* Are you writing for developers or for managers?
+* Are you writing for people who have a certain problem to solve?
+* Are you writing for a particular industry or market segment?
 
 ### Body of the overview
 
-Contains information that helps the developer or decision-maker get oriented to the API. Answers these questions.
+Contains information that helps the reader get oriented to the API. Answers these questions:
 
 * What is it supposed to do? (What problem does it solve, and for whom?)
 * What exact capabilities are available to the user? What services does it offer?
-* What does it NOT do that developers should know about?
+* What does it not do that developers should know about?
 * What are the typical use cases?
 * How does it work? (What do users need to know about architecture an internal components?)
 * What dependencies does the developer need to know about before installing?
-* What technical requirements? Including development environment and licensing.
+* What technical requirements do readers need? Include development environment and licensing requirements.
 * What knowledge prerequisites does the developer need to know about before using the API?
 
-### Postrequisites
+### Post-requisites
 
-* What comes next? Do you want to direct users to the quickstart to try it out?
-* How does one get started using the API?
+* What comes next? Do you want to direct users to the Quick Start to try it out?
+* How to get started with the API?
 
 ## More information
 
 ### Overview examples
 
-* **Chrome Native Client**. [The Native Client Technical Overview](https://developer.chrome.com/native-client/overview) explains an engine that allows C++ to run in the browser, including why it is a good solution for engineers who want to rework a desktop app and make it usable as a web app.
+* **Chrome Native Client**. [The Native Client Technical Overview](https://developer.chrome.com/native-client/overview) explains an engine that allows C++ to run in the browser, including why it's a good solution for engineers who want to rework a desktop app and make it usable as a web app.
 
-* **The Jira Platform**. [This overview of the Jira Platform](https://www.atlassian.com/software/jira/guides/getting-started/overview#about-the-jira-platform) does a good job of explaining multiple products and the associated use cases, uses, third-party integrations, hosting options, and licensing.
+* **The Jira Platform**. [This overview of the Jira Platform](https://www.atlassian.com/software/jira/guides/getting-started/overview#about-the-jira-platform) does a good job of explaining products and the associated use cases, third-party integrations, hosting options, and licensing.

api-quickstart/about-quickstart.md

@@ -1,37 +1,36 @@
-## What is a quickstart
+# What is a Quick Start
 
-* It should be a clear, concise, ordered step-by-step procedure.
-* It should describe the easiest way for them to achieve a result that shows off the capabilities of your product.
-* It should not delve into optimizations or advanced use cases.
+Quick Start Guides should be a clear, concise, ordered step-by-step procedure.
+They should describe the easiest way for readers to achieve a result that shows off the capabilities of your product.
+They should not delve into optimizations or advanced use cases.
 
-## Contents of your quickstart
+## Contents of your Quick Start
 
 ### Prerequisites
 
-* What knowledge do I need before I begin? 
-* What tasks must be completed (installation, configuring the environment?)
-* Where to get tokens or API keys, etc. if needed
+* What knowledge do readers need before they begin
+* What tasks do they need to complete (for example, software installation, environment configuration)
+* Where to get tokens or API keys, if needed
 
-### The main body should follow these guidelines
+### The main body
 
-* Start by telling users what the quickstart does. What task does this guide help the reader complete?
-* It should explain the basic operations that most users perform on the site, or the operations they might perform using the API.
-* Steps should be explained in the most logical order to complete a task
-* Each step should contain all the information necessary to complete it. It should exclude any extraneous information.
-* A step should include code samples (examples) that users can copy and paste, if executing code is necessary. Each code sample should be explained in comments that follow directly after the example, so newcomers can quickly understand how the API works.
+Start by telling users what the Quick Start does. What task does this guide help the reader complete?
+Explain the basic operations that most users perform on the site, or the operations they can perform using the API.
 
-### The quickstart should not include
+Explain steps in the most logical order to complete a task. Each step should contain all the information necessary to complete it, and exclude any extraneous information. Include code samples in steps so that readers can copy and paste. Explain each code sample in comments directly before or after the example, so readers can understand how the API works.
 
-* Setup information. (This means info about everything you have to do to make your work environment compatible and ready for the API.) Sometimes setup and quickstart type information end up together in a single volume called a "Getting Started" guide (or something similar). That's not necessarily wrong, but there are advantages to keeping the two types of information separate; namely, times when users no longer need the quickstart lesson, but want the setup information to create a work environment on a new machine.
-* Things that belong in the reference section, like authentication, throttling, error codes, a complete description of any feature.
-* Things that belong in the overview (a general description of the product; what it can do; what it can't do)
+### What not to include
 
-### Postrequisites
+Do not include setup information in your Quick Start, including anything that readers need to do to make their work environment compatible and ready for the API. Sometimes setup and Quick Start type information end up together in a single volume called a Getting Started Guide or similar. That's not necessarily wrong, but there are advantages to keeping the two types of information separate. Readers will often need the setup information, even when they no longer need the Quick Start lesson.
+
+Do not include content that belongs in the reference section, including authentication, throttling, error codes, or a complete description of any feature.
+
+Do not include content that belongs in the overview, including a general description of the product, or what the product can or can't do.
+
+### Post-requisites
 
 * What comes next?
 
 ## Links to examples
 
-* **Jekyll**. [This SSG](https://jekyllrb.com/docs/) offers an excellent quickstart. Note that the setup info is in a separate document, but it is linked in the first step.
-
-* **GitHub API**. [This collection of quickstarts](https://developer.github.com/apps/quickstart-guides/) from GitHub is worth a look. 
+* **Jekyll**. [This SSG](https://jekyllrb.com/docs/) offers a good example of a Quick Start. Note that the setup info is in a separate document, and linked to in the first step.

api-quickstart/api-quickstart.md

@@ -1,25 +1,24 @@
-# Quickstart template
+# Quick Start template
 
 ## Before you start
 
-Make sure you meet the following prerequisites before starting the tutorial steps:
+Before you begin, make sure you meet these prerequisites:
 
-* Prerequisite one
-* Prerequisite two
-* etc
+* Pre-requisite one
+* Pre-requisite two
 
 ## Get started
 
-## Step 1 - <One-sentence description of the step.>
+## Step 1 - One-sentence description of the step
 
 <!-- Fill in more details, as needed. -->
 
-## Step 2 - <One-sentence description of the step.>
+## Step 2 - One-sentence description of the step
 
 <!-- Fill in more details, as needed. -->
 
-<!-- Add additional steps, as needed. -->
+<!-- Add steps, as needed. -->
 
 ## What's next
 
-<!-- If you've just gotten a new user over the threshold so successfully using your API, what should they do next? -->
+<!-- If you've gotten a new user over the threshold using your API, what should they do next? -->

api-reference/about-api-reference.md

@@ -1,44 +1,45 @@
-# The API reference entry
+# API Reference entry
 
-## About the reference section
-
-The reference section is generally a collection of short entries, arranged in alphabetical order. This template addresses the individual reference entry that you create for a single endpoint. 
+The reference section is a collection of short entries, arranged in alphabetical order. This template is for the individual reference entry that you create for a single endpoint.
 
 The reference section is important for API documentation. New users will start with other documents to help them get going, but experienced users will refer more frequently to the reference section for the detailed information they need to make use of the API.
 
-The reference section should contain a full listing of endpoints, methods, and parameters
+The reference section should contain a full listing of endpoints, methods, and parameters.
 
-## The general contents
+## Content of the reference entry
 
 ### Reference entries
 
-Each reference listing should ideally contain:
+Each reference listing should contain:
 
-* A general description of the endpoint in question (What is it for, and what can it do?)
+* A general description of the endpoint, including what it's for, and what it can do
 * The HTTP method, if applicable
 * An example of the syntax
-* All the parameters for the endpoint (And for each parameter, see the requirements below)
+* All the parameters for the endpoint
+
+For each parameter, include:
+
 * An example request
 * An example response
-* Response schema
+* The response schema
 
 ## Best practices for reference docs
 
-Each detailed reference entry should contain all the information a user might need to know when using the feature.
+Each detailed reference entry should contain all the information readers need to know when using the feature.
 
-For parameters, include these:
+For parameters, include:
 
-   * name (the actual parameter that users will pass)
-   * Description of what the parameter does and when to use it
-   * Data type
-   * All the acceptable values, if there is a limited set of options
-   * whether the parameter is required or optional
+* Name of the parameter
+* Description of what the parameter does and when to use it
+* Data type
+* All the acceptable values, if there is a limited set of options
+* Whether the parameter is required or optional
 
-Differentiate the endpoint you are documenting from other similar endpoints. If more than one endpoint or parameter can get the job done, explain which one pertains to what situation. (Each probably exists for a specific reason, but the user needs to know.)
+Differentiate the endpoint from other similar endpoints. If more than one endpoint or parameter can achieve the same result, explain which one to use in what situation, as each probably exists for a specific reason.
 
-Each reference entry should include both a syntax and a working example. The example code should be followed by extensive comments that explain how it works.
+Include both syntax and a working example for each reference entry. Follow example code with extensive comments that explain how it works.
 
 ## Examples
 
 examples:
-[API reference of various resource types](https://developers.google.com/gmail/api/v1/reference)
+[API reference of resource types](https://developers.google.com/gmail/api/v1/reference)