Merge branch 'thegooddocsproject:dev' into base-restructure

.github/ISSUE_TEMPLATE/create-new-doctype-template.md

@@ -0,0 +1,33 @@
+---
+name: Create new doc type template
+about: For issues where a templateer needs to create a new doc type template.
+title: Create {doc_type} template
+labels: templates
+assignees: ''
+
+---
+
+# Create {doctype} template
+
+## Description
+### Doc Type Name: {doc_type}
+### Directory: https://github.com/thegooddocsproject/templates/{directory_name}
+### Sub-tasks
+1. Create {doc_type}-template.md and write content for it
+2. Create {doc_type}-guide.md and write content for it
+
+{Optional: add any further explanation if the issue is not self-explanatory}
+
+## Helpful Resources
+{Optional: Add links to anything that might help the templateer write this particular type of template. For example, a Medium article about how to write good tutorials.}
+
+## Before You Submit
+Add an appropriate label to denote the relative priority of this template:
+
+Label | Description
+--|--
+`templates-p0`| Base template, required to start other templates
+`templates-p1` | 1.0 MVP alpha release: Key doctypes that authors need help with.
+`templates-p2` | 2.0 Common doctypes used within open source.
+`templates-p3` | 3.0 Comprehensive set of doctypes
+`templates-p4` | 4.0 Special case doctypes

reference/about-reference.md

@@ -13,7 +13,7 @@ A reference article works well when it:
 
 ### The Overview section
 
-Summarise what this reference article is about. 
+Summarize what this reference article is about. 
 
 * Explain what all the entries defined on the page have in common.
 
@@ -24,8 +24,6 @@ In most cases, reference information is easiest to express as a table.
 
 Use the "don't repeat yourself" (DRY) method and re-use content if it's written for the same audience, and it fits within your reference document without modification.
 
-If you need to refer to a screen in a UI, use a table to explain elements in the UI and their meanings. Include screenshots, and use call-outs to help your audience find each element in the table.
-
 ### Code-generated documentation
 
 Reference documentation can often be auto-generated from source code and/or comments within the code. It is typically easier to keep auto-generated docs current, accurate and complete, as the documentation is maintained next to the code it describes.

reference/template-reference.md

@@ -2,7 +2,7 @@
 
 ## Overview
 {Document author tip:
-Summarise what this reference article is about. Explain what all the entries defined on the page have in common. What you put here is reused in the Overview section of your doc site and included in HTML description tags. For help with writing and structuring a reference article, see the file about-reference.md in this directory. Check out https://www.markdownguide.org/basic-syntax/ if you need help with markdown syntax.
+Summarize what this reference article is about. Explain what all the entries defined on the page have in common. What you put here is reused in the Overview section of your doc site and included in HTML description tags. For help with writing and structuring a reference article, see the file about-reference.md in this directory. Check out https://www.markdownguide.org/basic-syntax/ if you need help with markdown syntax.
 }
 
 {Document author tip: It can be helpful to split up your reference page into subsets of related enries. For example, the reference page for an API endpoint might include subsets of entries for "General Requirements", "Request Parameters", and "Responses"}. The formats of entries might be different for each subset; for example, "General Requirements" might be a bulleted list, while "Request Parameters" and "Responses" are tables.
@@ -21,49 +21,3 @@ Summarise what this reference article is about. Explain what all the entries def
 |||||
 
 }
-
-{Document author tip: Here is a starter table for a subset of entries for UI form-field references. Each entry refers to an element in the screenshot.
-
-## Form-field References
-
-![Field reference](https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAA/Resources/Images/Forms/kbf2.x1.jpg)
-
-|Name |Type |Required |Description |
-|:--- |:--- |:--- |:--- |
-|Company|`string`|No|The name of the company the person works at or is representing.|
-|First Name|`string`|Yes|The first name of the person requiring training.|
-|Last Name|`string`|Yes|The surname of the person requiring training.|
-
-{Document author tip: Here is example HTML for a nested table.
-
-<table>
-  <tr>
-    <th>Col 1</th>
-    <th>Col 2</th>
-  </tr>
-  <tr>   
-    <th>Cell 1.1</th>
-    <th>Cell 1.2</th>
-  </tr>
-  <tr>
-    <th>Cell 2.1</th>
-    <th>Cell 2.2
-        <table>
-            <tr>
-              <th>Nested header 1</th>
-              <th>Nested header 2</th>
-            </tr>
-            <tr>   
-              <th>Nested cell 1</th>
-              <th>Nested cell 2</th>
-            </tr>  
-        </table>
-    </th>
-  </tr>
-  <tr>
-     <th>Cell 3.1</th>
-     <td>Cell 3.2</td>     
-  </tr>
-</table>
-
-}

templates-list.md

@@ -0,0 +1,50 @@
+# List of Templates to Create
+
+The list below includes all the templates we as templateers plan to create. Feel free to provide feedback on whether any templates need to be removed or added to the list. The "P{number}" before each item indicates the priority of completing this template. We want to focus mostly on completing P1 templates, but if you have a special interest in one of the other templates feel free to work on that too. Feedback on the priorities is also welcome. Items without "P{number}" are just categories, not templates to be created.
+
+* P0 Base
+	* P1 Reference
+		* P3 api-reference
+		* P2 Glossary
+		* P4 FAQ
+	* *Manual*
+		* P2 User guide
+		* P3 Installation guide
+		* P3 Developers' guide
+		* P4 Administrators’ guide
+		* P2 Defining personas guide
+	* *Task*
+		* P1 Tutorial
+		* P1 How-to
+			* P1 Quickstart
+				* P3 Api-quickstart
+	* *Concept*
+		* P2 Business overview (About page, Landing page)
+		* P4 Technical overview
+		* P4 Case Study
+		* P4 White paper
+		* P2 Explanation
+	* *Community*
+		* P0 Community definitions
+		* P1 README
+		* P2 Contributors' guide
+		* P2 Code of Conduct
+		* P3 Issue template and merge request template
+		* P3 Project Governance - RFC processes?
+		* P3 License (Recommendations on attribution)
+	* *Guide*
+		* P3 Style guide (for code)
+		* P3 Style guide (for documentation)
+	* P3 Release notes
+	* P4 Logging
+	* P4 Pull request template
+	* P4 Bug reporting template
+	* P4 Comments (structured comments you can grok and grep)
+	* P4 Error messages
+	* *Plan*
+		* P4 Information Architecture
+		* P4 Documentation Plan
+	* *Requirements*
+		* P3 User Stories
+		* P3 Engineering Requirements
+	* P3 Tests