thegooddocsproject · acpkendo · Oct 14, 2020 · Nov 4, 2020 · camerons · Nov 15, 2020
diff --git a/toolchain/README.md b/toolchain/README.md
@@ -0,0 +1,2 @@
+# toolchain
+This folder is the holding place for planning documentation for The Good Docs Toolchain, a project to create a collection of tools to make authoring technical documentation easier.
diff --git a/toolchain/personae.md b/toolchain/personae.md
@@ -0,0 +1,56 @@
+---
+title: The Good Docs Toolchain
+---
+
+This document summarizes the personae for The Good Docs Toolchain, a collection of tools designed to help users create better technical documentation.
+
+The following are the primary types of users (i.e. personae) targeted by this toolchain. Each has a number of distinct needs, as outlined in the below sections.
+
+# Tech writer
+
+The **Tech Writer** is an individual whose primary role is authoring technical documentation. These may be volunteers in open source projects or employees in commercial organizations. They will typically have a certain level of technical proficiency, although this will range from a simple understanding of technical concepts to full proficiency with tools such as the command line.
-The **Tech Writer** is an individual whose primary role is authoring technical documentation. These may be volunteers in open source projects or employees in commercial organizations. They will typically have a certain level of technical proficiency, although this will range from a simple understanding of technical concepts to full proficiency with tools such as the command line.
+The **Tech Writer** is an individual whose primary role is authoring technical documentation. They can be volunteers in open source projects or employees in commercial organizations. They typically have a certain level of technical proficiency, although this ranges from a simple understanding of technical concepts to full proficiency with tools such as the command line.
-The **Tech Writer** is an individual whose primary role is authoring technical documentation. These may be volunteers in open source projects or employees in commercial organizations. They will typically have a certain level of technical proficiency, although this will range from a simple understanding of technical concepts to full proficiency with tools such as the command line.
+The **Tech Writer** is an individual whose primary role is authoring technical documentation. They can be volunteers in open source projects or employees in commercial organizations. They typically have a certain level of technical proficiency, although this ranges from a simple understanding of technical concepts to full proficiency with tools such as the command line.
+
+As a tech writer...
+
+- I want to use a simple tool to manage docs-as-code so I can concentrate on writing.
+- I want to have access to spell/grammar check so I can take advantage of existing tools.
- I want to have access to spell/grammar check so I can take advantage of existing tools.
+- I want to have access to spelling and grammar checking so I can take advantage of existing tools.
- I want to have access to spell/grammar check so I can take advantage of existing tools.
+I want to have access to spelling/grammar and/or linting tools, or integrate existing options and tools
- I want to have access to spell/grammar check so I can take advantage of existing tools.
+- I want to have access to spelling and grammar checking so I can take advantage of existing tools.
- I want to have access to spell/grammar check so I can take advantage of existing tools.
+I want to have access to spelling/grammar and/or linting tools, or integrate existing options and tools
+- I want to have the option to use the editor of my choice so I don't have to learn something new.
+
+# Developer
+
+Often times **Developers** are called on to document the code or application they've created. In business this may be a matter of convenience, where in open source projects there may simply not be anyone else available. But in either case this is a secondary task added to their main roles, often without enough thought given to the effort required to produce something of quality. These individuals are (obviously) very technically savvy, although this doesn't preclude them from wanting to use GUI tools.
-Often times **Developers** are called on to document the code or application they've created. In business this may be a matter of convenience, where in open source projects there may simply not be anyone else available. But in either case this is a secondary task added to their main roles, often without enough thought given to the effort required to produce something of quality. These individuals are (obviously) very technically savvy, although this doesn't preclude them from wanting to use GUI tools.
+**Developers** are often called on to document the code or application they've created. In business this may be a matter of convenience, where in open source projects there may not be anyone else available. But in either case this is a secondary task added to their main roles, often without enough thought given to the effort required to produce something of quality. These individuals are very technically knowledgeable, although this doesn't preclude them from wanting to use GUI tools, or other assistance to write well.
-Often times **Developers** are called on to document the code or application they've created. In business this may be a matter of convenience, where in open source projects there may simply not be anyone else available. But in either case this is a secondary task added to their main roles, often without enough thought given to the effort required to produce something of quality. These individuals are (obviously) very technically savvy, although this doesn't preclude them from wanting to use GUI tools.
+**Developers** are often called on to document the code or application they've created. In business this may be a matter of convenience, where in open source projects there may not be anyone else available. But in either case this is a secondary task added to their main roles, often without enough thought given to the effort required to produce something of quality. These individuals are very technically knowledgeable, although this doesn't preclude them from wanting to use GUI tools, or other assistance to write well.
+
+As a developer...
+
+- I want help in deciding what form the required documentation should take so I don't need to learn technical writing theory.
- I want help in deciding what form the required documentation should take so I don't need to learn technical writing theory.
+- I want templates and guides to help structure the documentation I'm to create so I don't need to learn technical writing theory.
- I want help in deciding what form the required documentation should take so I don't need to learn technical writing theory.
+- I want templates and guides to help structure the documentation I'm to create so I don't need to learn technical writing theory.
+- I want help to stage the required documentation so I don't need to create everything from scratch.
- I want help to stage the required documentation so I don't need to create everything from scratch.
+- I want guides and templates to help me get started with documentation so I don't need to create everything from scratch.
- I want help to stage the required documentation so I don't need to create everything from scratch.
+- I want guides and templates to help me get started with documentation so I don't need to create everything from scratch.
+
+# Reviewer
+
+**Reviewers** can take many forms, from technical leads and delivery managers responsible for the solution as a whole to subject matter experts who may be getting their first look at the solution they themselves will use. The reviewer's role is to look over the documentation and provide *feedback* to be incorporated back into the material.
-**Reviewers** can take many forms, from technical leads and delivery managers responsible for the solution as a whole to subject matter experts who may be getting their first look at the solution they themselves will use. The reviewer's role is to look over the documentation and provide *feedback* to be incorporated back into the material.
+**Reviewers** can take many forms, from technical leads and delivery managers responsible for the solution, to subject matter experts who may be getting their first look at the solution they themselves will use. The reviewer's role is to look over the documentation and provide feedback to be incorporated into the content.
-**Reviewers** can take many forms, from technical leads and delivery managers responsible for the solution as a whole to subject matter experts who may be getting their first look at the solution they themselves will use. The reviewer's role is to look over the documentation and provide *feedback* to be incorporated back into the material.
+**Reviewers** can take many forms, from technical leads and delivery managers responsible for the solution, to subject matter experts who may be getting their first look at the solution they themselves will use. The reviewer's role is to look over the documentation and provide feedback to be incorporated into the content.
+
+As a reviewer...
+
+- I want to look review the documentation in its final presentation so I can better visualize how it's used.
+- I want the ability to easily add comments to it so the review process is easy to track.
- I want the ability to easily add comments to it so the review process is easy to track.
+- I want the ability to easily add comments to the content so the review process is easy to track.
- I want the ability to easily add comments to it so the review process is easy to track.
+- I want the ability to easily add comments to the content so the review process is easy to track.
+
+As a technical reviewer...
+
+- I want the ability to make corrections directly in the documentation's source so I don't need to go through the review process.
+
+# Marketing
+
+While **Marketing** reviewer are the same as technical reviewers in many ways (and many of the same needs will apply), they are also looking after the company's branding, and therefore may have additional requirements.
-While **Marketing** reviewer are the same as technical reviewers in many ways (and many of the same needs will apply), they are also looking after the company's branding, and therefore may have additional requirements.
+**Marketing** reviewers are similar to technical reviewers in many ways, and many of the same needs will apply. However, they are also looking after the company's branding, and therefore have additional requirements.
-While **Marketing** reviewer are the same as technical reviewers in many ways (and many of the same needs will apply), they are also looking after the company's branding, and therefore may have additional requirements.
+**Marketing** reviewers are similar to technical reviewers in many ways, and many of the same needs will apply. However, they are also looking after the company's branding, and therefore have additional requirements.
+
+As a marketing reviewer...
+
+- I want the ability to comment on the look-and-feel of the deliverables, so I can ensure they're in line with the brand.
+
+# Technology decision-maker
+
+The **Technology Decision Maker** may weigh in on the documentation as a 
+
+As a technology decision maker...
+
+- I want to provide feedback on the approach to the deliverable(s), to ensure it's meeting expectations as part of the overall solution.
- I want to provide feedback on the approach to the deliverable(s), to ensure it's meeting expectations as part of the overall solution.
+- I want to provide feedback on the approach to the documentation, to ensure it's meeting expectations as part of the overall product.
- I want to provide feedback on the approach to the deliverable(s), to ensure it's meeting expectations as part of the overall solution.
+- I want to provide feedback on the approach to the documentation, to ensure it's meeting expectations as part of the overall product.
+- I want to enforce the docs-as-code approach, to ensure it's in line with my high-level strategy for the product(s).
- I want to enforce the docs-as-code approach, to ensure it's in line with my high-level strategy for the product(s).
+- I want to encourage the docs-as-code approach, to ensure it's in line with my high-level strategy for the product.
- I want to enforce the docs-as-code approach, to ensure it's in line with my high-level strategy for the product(s).
+- I want to encourage the docs-as-code approach, to ensure it's in line with my high-level strategy for the product.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# toolchain
		This folder is the holding place for planning documentation for The Good Docs Toolchain, a project to create a collection of tools to make authoring technical documentation easier.