Does your project need docs but you don’t know how to start? The Good Docs Project templates can help, now in Asciidoc. Use the templates in this repository to create quality docs faster and easier for free.
The Good Docs Project is an open-source project working to provide templates for a variety of common content types used in most software documentation projects. This project is a conversion of their templates for writers who use the Asciidoc markup language.
The templates are for anyone who wants to make better software documentation. This includes:
-
Developers who want to create good documentation for their software quickly and easily, but don’t know where to start.
-
Documentation project owners working in a docs-as-code model and who you want to provide templates to non-writers to help them write better documentation.
-
Technical writers who want to standardize their documentation and draw inspiration from high-quality templates for their own templates or documentation projects.
The templates are organized into template packs. A template pack is a collection of templates organized together by:
-
Common use cases or tasks.
-
Needs of particular audiences or stakeholders.
-
Popular or notable documentation frameworks.
-
Maturity models for documentation.
If you are unsure which template pack is right for you, the project recommends starting with the Core documentation pack. The core documentation pack is the flagship template pack and it includes the core, fundamental content types that every documentation project needs. If you download one template pack for your project, it should be this one.
Each individual template within the template packs contains a set of files:
| File | Example filename and purpose |
|---|---|
Template file |
template-content-type.adoc The template file is the raw template for the content type. It provides a rough outline of the suggested content and a few embedded writing tips for how to fill in the different sections of the template. |
Template guide |
guide-content-type.adoc This guide provides a deeper explanation of how to fill in the template. It provides a lightweight introduction to the purpose of this documentation and explains how to fill in each section of the document. |
Resources |
resources-content-type.adoc This document includes the resources (books, blog entries, guides) that the template author(s) used during the research phase of creating the template. It also includes any high-quality examples of that content type that served as inspiration for the template. |
Process |
process-content-type.adoc This document explains best practices for researching, writing, and maintaining this content type. |
Example |
example-content-type.adoc See an example of the template in action in the model documentation project: The Chronologue. |
|
Note
|
Not all templates contain all these files, but the goal of The Good Docs Project is to eventually provide these files for each template. |
You can click the links in the following table to access the template files. You can then download or copy and paste these files into your documentation project as needed.
The core documentation pack is the flagship template pack and it includes the core, fundamental content types that every documentation project needs. If you download one template pack for your project, it should be this one.
| Template | Description |
|---|---|
An explanation of a concept, context, or background information about a product or its features. |
|
A concise set of numbered steps to do one task with the product. |
|
Information users need to know about your project, including how users can engage with the project and get started with the tool. |
|
Specific, in-depth details about a particular topic. |
|
Communicate new features, improvements, bug fixes, and known issues about a product to users and stakeholders. |
|
Instructions for setting up an example project using the product, intended for the purpose of hands-on learning. |
|
A list of common problems (referred to as "symptoms") experienced by users, an explanation of the causes, and steps to resolve the issue. |
The open source community docs template pack includes the fundamental content types that every open source project needs to have a healthy and productive community.
| Template | Description |
|---|---|
The bug report is an issue template that your users can fill out to provide you with higher-quality, actionable bug issues for your product. |
|
A code of conduct to help you govern your open source or developer community and ensure it remains healthy and open. This template goes beyond a mere code of conduct to provide you with a response plan and supplementary materials to effectively respond to a code of conduct incident. |
|
Tells users how they can contribute to your open source project and join the community. |
|
Helps you clearly communicate who belongs to your open source project or organization and how contributors can contact or work with them. |
|
Information users need to know about your project, including how users can engage with the project and get started with the tool. |
These templates help you create additional content types beyond the Core documentation pack. The templates in this pack help you create content you need as your documentation project matures.
| Template | Description |
|---|---|
Simplest possible method of implementing your API. |
|
List of references related to your API. |
|
A contact support page typically includes a list of the communication channels, discussion forums, and links to other resources to assist users with issues that they are having with your product. |
|
A reference document that lists and organizes terms and their definitions that are unique to your organization or which you use in a specific way. |
|
Explain all the necessary steps to install the product and set it up for further use. |
|
A quickstart introduces your users to your application for the first time. It focuses on the primary feature of the application and helps your users to start using the application as quickly as possible. |
|
A style guide provides project contributors with general guidelines for writing project documentation. The overall goal of a style guide is to ensure quality and consistency throughout the project’s documentation, which is especially important if different authors are contributing to the documentation over time. |
|
Using this template, writing teams can ensure they consistently use and translate the same terms across all the documentation in their system. |
|
User personas are a framework to identify the characteristics that differentiate each user type for your product or service. Discovering more about your users will help you make user-centric product decisions and produce better documentation. |
Not all articles from the original project have been converted to Asciidoc yet. See the following tables for the current status.
| Template | Converted | Reviewed |
|---|---|---|
api-quickstart |
☑ |
☐ |
api-reference |
☑ |
☐ |
bug-report |
☑ |
☐ |
code-of-conduct |
☑ |
☐ |
concept |
☑ |
☐ |
contact-support |
☑ |
☐ |
contributing-guide |
☐ |
☐ |
glossary |
☐ |
☐ |
how-to |
☐ |
☐ |
installation-guide |
☐ |
☐ |
our-team |
☐ |
☐ |
… |
| Content | Converted | Reviewed |
|---|---|---|
.gitlab/* |
☑ |
☐ |
README |
☑ |
☐ |
writing-tips |
☑ |
☐ |
To provide feedback related to the Asciidoc version of the templates, open a GitHub issue in this repository.
To provide feedback related to the original templates, use the project’s feedback form. You can also open an issue.
See the Contributing guide for information about joining the community and contributing to the templates project.