diff --git a/toolchain/README.md b/toolchain/README.md new file mode 100644 index 0000000..63800e2 --- /dev/null +++ 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 new file mode 100644 index 0000000..5c2ad04 --- /dev/null +++ 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. + +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 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. + +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 to stage the required 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. + +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. + +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. + +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 enforce the docs-as-code approach, to ensure it's in line with my high-level strategy for the product(s).