About The Good Docs Project

This page introduces the concepts used by The Good Docs Project for creating, customizing, and using documentation templates. It is designed to help document authors, docset owners, and template authors to get started with The Good Docs Project.

Goals of The Good Docs Project

Within The Good Docs Project, we build best practice templates and writing instructions for documenting open source software. (Which incidentally are useful for all software and related domains.)

Focus on what you’re best at

Templates enable significant efficiencies by allowing experts to focus only on the bits they do best.

Various writing experts can embed best practices into a template.
Domain experts can write better content, more efficiently, when they have a template to work against.
Writers can polish the content by reviewing for compliance against the template.

Various doctypes

There is no one thing called “Good Docs”; there are multiple doctypes, each with different purposes and needs. Targeting your writing to the purpose will improve the quality and impact of your project’s documentation, often significantly.

Doc Types Diagram — Plotting doc types within a maturity model

Our templates provide tailored guidance with different priorities for each doctype.

For instance:

Reference documents need to be current, but it is okay if sentence structure is not polished.
Tutorials should be polished, but they don’t need to cover the latest features.

Doctype template set

For each doctype, we provide a set of supporting documents, which we call a template-set. These documents are based on our base-template-set, which is effectively our template for templates.

Raw template (what - structural):

Layout of headings and sample text with embedded writing tips.

Template guide (how):

Provides guidance on how to fill out each section in the template.

Template theory (why - conceptual):

Provides background theory which supports authors in making documentation decisions.
Empowers an author to “think like a tech writer”.

Template checklist (how):

Checklist to confirm you have covered everything.

Template example (what)

Filled-in template which describes a fake project.

Roles

We consider the following primary roles when creating templates:

Template author

Creates a {doctype}-template set, based on the base template-set.

Docset owner

Establish a content strategy.
Selects a set of doctype templates for a project, and tailors them for the project’s needs.

Doc author

Follows the Quickstart for Document Authors and the {doctype}-guide to write a document.

Doc Reader

Reads intuitive documentation, tailored for this reader’s needs, presented when the reader needs it.