GoodDocs

Many of the docs we write exist to help teams make better decisions by writing down the thinking and reviewing it with others. With AI, it is easier than ever to generate a doc from a few words of a prompt, but when a draft looks “done” too quickly, important context and key aspects can get skipped. That is why teams often adopt doc templates: they force the right questions to show up every time.

There are real benefits to standardized doc formats when you work with many people. A consistent template reminds you of the things you missed before and trains the team to avoid repeating past mistakes. It keeps everyone aligned on what needs to be answered, makes reviews dramatically faster, and helps new teammates find what they need without decoding each author’s personal style.

The downside is toil: filling in every section takes time, which is exactly when people reach for AI and generate a draft from a few keywords. That is useful, but it can also skip critical thinking. The challenge is letting people use AI for speed while still ensuring the important parts are covered. That is where GoodDocs comes in.

GoodDocs solves that by making documentation easy to write and easy to trust, even when AI helps produce the first draft. It encourages using AI as a thought-partner and research-partner, with an additional review layer that checks for missing reasoning, while still reducing toil so doc creators can focus on shipping real improvements for customers and business impact.

We already have all the pieces: GitHub for storage and version control, GitHub Actions on PRs to run validation automatically, Codex/Claude-Code/GitHub Copilot CLI as the orchestration and review layer, and VS Code/Cursor as the editor. GoodDocs brings those parts together into a single, lightweight system for structured docs.

How to use it

1. Setup by:
   • Creating a repo using GoodDocs as a template.
   • Cloning your repo locally.
2. Initialize the repo defaults with make init. This is a 1-time step.
3. Run Codex/Claude-Code/GitHub Copilot CLI in your repo in terminal.
4. Create a new doc with make new-doc, then draft it using the $doc-author skill.
5. Edit your doc using your favorite editor, filling out all the sections.
6. Share your doc by opening a PR from your branch.
7. Validation runs automatically, and optional LLM review can run when enabled (ensure OPENAI_API_KEY is set in https://github.com/your_account/repo/settings/secrets/actions)

Example

This repository includes a complete example document at docs/example/0001-example.md. It follows the template, passes validation, and shows the expected level of detail across sections like Motivation, Proposed Solution, and Alternatives & Open Questions.

You can view a sample PR where the LLM left template-based review comments here.

How to customize it

(You want to do this to get the real value out of this)

You can tune GoodDocs to match your org. In your repo that you created from GoodDocs as a template:

Update templates/doc-template.md to change the doc format, and edit schema/doc_rules.json to adjust validation rules, required sections, or quality heuristics. If you need multiple doc types, add new templates and doc type entries so each format has its own rules and folder.

Common customization examples and why they help:

• PRDs to capture customer context, success metrics, and rollout plans in a consistent way.
• Dev design docs / RFCs to force clarity on trade-offs, API contracts, and migration plans before code is written.
• Decisions (ADR-style) to keep a durable record of why a choice was made and what alternatives were considered.
• Operations / incident playbooks to standardize escalation, post-mortem learnings, runbooks, and recovery steps.
• Compliance or security reviews to ensure required checks are documented and auditable.