tomevault-io 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:
- Quick start (get running in <5 minutes)
- Common use cases
- Advanced features
- API reference
- 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.
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/aaronbassett) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->