When should I create an Architecture Decision Record (ADR)?

An ADR should be created whenever you make a significant architectural choice that will impact the project long-term, providing context and consequences for future developers.

How does this skill improve README files?

It provides a minimal, effective structure that prioritizes 'Quick Start' and 'Setup' sections, ensuring users can find the fastest path to running the project.

What is the 'Why Not What' principle?

It is the philosophy that code should be written clearly enough to explain what it is doing, while comments should be reserved for explaining the reasoning, trade-offs, and decisions behind the code.

Does this skill support automated documentation tools?

Yes, it includes guidance for using Lychee for fast link checking and Vale for enforcing prose style guides like Google or Microsoft standards.

Documentation Standards

Name: Documentation Standards
Author: phrazzld

byphrazzld

•

Learning & Documentation

Enforces best practices for technical documentation by prioritizing code clarity and explaining the reasoning behind implementation decisions.

About

This skill provides a comprehensive framework for maintaining high-quality software documentation, focusing on the 'why not what' principle to ensure comments add value beyond the code itself. It guides users through creating effective README files, Architecture Decision Records (ADRs), and automated documentation maintenance workflows using tools like Vale and Lychee. By encouraging minimal yet impactful documentation, this skill helps development teams reduce technical debt and maintain a clear, reliable source of truth for their projects across the entire software development lifecycle.

Key Features

Provides criteria for when to update or delete stale documentation
Optimizes public API contracts and code comment density
Applies the 'Why Not What' commenting principle for clearer intent
2 GitHub stars
Standardizes README.md, ADR, and ARCHITECTURE.md structures
Guides automated link checking and style linting integration

Use Cases

Setting up comprehensive documentation for a new open-source project
Automating documentation quality checks within a CI/CD pipeline
Reviewing pull requests to ensure comments explain logic rather than restating code

About

Key Features

Provides criteria for when to update or delete stale documentation
Optimizes public API contracts and code comment density
Applies the 'Why Not What' commenting principle for clearer intent
2 GitHub stars
Standardizes README.md, ADR, and ARCHITECTURE.md structures
Guides automated link checking and style linting integration

Use Cases

Setting up comprehensive documentation for a new open-source project
Automating documentation quality checks within a CI/CD pipeline
Reviewing pull requests to ensure comments explain logic rather than restating code