readme-and-co:documentation-standards

Documentation Standards for GitHub Repositories

Purpose

Provide comprehensive guidance for creating high-quality GitHub repository documentation following industry best practices. This skill covers README structure, contributing guidelines, support resources, and documentation organization.

When to Use This Skill

Use this skill when:

• Creating README.md files for repositories
• Writing CONTRIBUTING.md guides
• Generating SUPPORT.md documentation
• Structuring repository documentation
• Deciding what sections to include in documentation
• Following documentation best practices

Core Documentation Types

README.md

The README is the entry point to any repository. Essential sections include:

Must-have sections:

• Project title and description (one-line summary)
• Installation instructions
• Usage examples
• License information

Recommended sections:

• Features list
• Prerequisites/requirements
• Contributing link
• Support/contact information
• Acknowledgments

Optional but valuable:

• Badges (build status, coverage, version)
• Screenshots/demos
• Tech stack overview
• Roadmap
• FAQ

Structure pattern:

# Project Name

Brief description (1-2 sentences)

## Features

## Installation

## Usage

## Contributing

## License

CONTRIBUTING.md

Guides contributors through the contribution process.

Essential elements:

• How to set up development environment
• Code style guidelines
• Testing requirements
• Pull request process
• Commit message conventions

Structure levels:

Basic (for simple projects):

• Development setup
• How to submit changes
• Code of conduct link

Standard (recommended):

• Development environment setup
• Running tests
• Code style (linting, formatting)
• Pull request process
• Issue reporting guidelines

Comprehensive (for large projects):

• All standard sections plus:
• Architecture overview
• Testing strategy
• Release process
• Contribution recognition
• Detailed workflow examples

SUPPORT.md

Defines how users get help.

Key sections:

• Where to ask questions (GitHub Discussions, Stack Overflow, Discord)
• How to report bugs (link to issue templates)
• Support resources (documentation, FAQ, tutorials)
• Response time expectations (if applicable)

Variants:

Basic: Links to issue tracker and communication channels

Detailed: Includes troubleshooting guides, FAQ, escalation paths

Documentation Principles

Clarity Over Completeness

Write for the target audience:

• End users: Focus on installation and usage
• Contributors: Emphasize development setup and guidelines
• Maintainers: Include architecture and maintenance docs

Progressive Disclosure

Structure documentation from basic to advanced:

1. Quick start (get running in <5 minutes)
2. Common use cases
3. Advanced features
4. API reference
5. Architecture details

Maintain Consistency

Across files:

• Use consistent terminology
• Match code style in examples
• Link between documents appropriately

Within files:

• Consistent heading levels
• Uniform code block formatting
• Standard section ordering

Keep Updated

Documentation rots quickly. Strategies:

• Link to canonical sources (not duplicate information)
• Use automated tools for version numbers, API references
• Include "last updated" dates for time-sensitive content
• Review documentation in PR process

Project-Specific Customization

Adapt documentation to project characteristics:

Language/Framework:

• Python: Include requirements.txt/pyproject.toml, virtual env setup
• JavaScript: Include package.json scripts, npm/yarn/pnpm
• Go: Include go.mod, go install instructions
• Rust: Include Cargo.toml, cargo build/run

Project Type:

• Library: Emphasize API documentation, installation
• Application: Focus on usage, configuration
• CLI tool: Include command reference, examples
• Framework: Provide getting started guide, concepts

Audience:

• Open source: Emphasize contributing, community
• Internal tool: Focus on organization-specific setup
• Commercial: Include licensing, support channels

README Patterns by Project Type

Library/Package

# Library Name

Description of what the library does

## Installation

[Package manager commands]

## Quick Start

[Minimal example]

## API Reference

[Key functions/classes]

## Examples

[Common use cases]

Application/Service

# Application Name

What the application does and why

## Features

[Key capabilities]

## Getting Started

### Prerequisites
### Installation
### Configuration

## Usage

[How to use the application]

## Deployment

[Production deployment guide]

CLI Tool

# Tool Name

One-line description

## Installation

[Install command]

## Usage

```bash
tool-name [options] <arguments>

Commands

[Command reference]

Examples

[Common workflows]

## Documentation Anti-Patterns

**Avoid:**
- Duplicating information that exists in code comments
- Screenshots that become outdated quickly
- Installation instructions for every OS when package managers work cross-platform
- Extensive API documentation in README (link to generated docs)
- Mixing user docs with contributor docs

**Instead:**
- Link to generated API docs
- Use badges for CI status, not screenshots
- Focus on primary installation method, link to wiki for alternatives
- Separate user docs (README) from contributor docs (CONTRIBUTING)

## Additional Resources

### Reference Files

For detailed guidance and examples:
- **`references/readme-examples.md`** - Analysis of stellar README files with patterns extracted
- **`references/contributing-patterns.md`** - Contributing guide structures from major projects
- **`references/support-structures.md`** - Support documentation examples and patterns

### Example Files

Working documentation templates in `examples/`:
- **`examples/README-minimal.md`** - Minimal README template
- **`examples/README-standard.md`** - Standard README with common sections
- **`examples/CONTRIBUTING-basic.md`** - Basic contributing guidelines

## Quick Reference

**README checklist:**
- [ ] Clear title and description
- [ ] Installation instructions
- [ ] Usage example
- [ ] License specified
- [ ] Contributing link (if accepting contributions)

**CONTRIBUTING checklist:**
- [ ] Development environment setup
- [ ] Testing instructions
- [ ] PR process explained
- [ ] Code style guidelines
- [ ] Code of conduct link

**SUPPORT checklist:**
- [ ] Where to ask questions
- [ ] How to report bugs
- [ ] Available resources
- [ ] Response expectations

Consult reference files for detailed patterns and real-world examples.