14 KiB
14 KiB
title, description, tags
| title | description | tags | ||||
|---|---|---|---|---|---|---|
| README Authoring | Best practices and templates for generating README sections following standards |
|
README Authoring Patterns
Metadata
Purpose: Provide 8-section minimal README templates and generation patterns Version: 1.0.0
Instructions
Minimal README Structure
The Personal README follows an 8-section minimal structure with a link-first approach:
- Project Title & One-Liner - Name + 1-2 sentence description
- Badges Block (optional) - Version, lifecycle, docs, code style
- Short Description - Business problem/solution + core functionality (3-5 sentences)
- Installation - Simple command or link to detailed setup
- Documentation - Links to key resources (architecture, ADRs, guides)
- Supporting Components (optional) - Related repos/services
- Contributing - How to contribute or link to CONTRIBUTING.md
- Bugs & Enhancements - Issue tracker link
Section Generation Reference
| Section | Template | Key Requirements | Common Sources |
|---|---|---|---|
| 1. Title & One-Liner | # {Name}{1-2 sentence description} |
Project name + what it does | pyproject.toml, package.json, setup.py |
| 2. Badges (optional) | Wrapped in <!-- badges: start/end --> comments |
MVP/Production tier - see badge options below | Version from metadata, lifecycle from tier, code style from .pre-commit-config.yaml |
| 3. Description | Business problem + solution + functionality (3-5 sentences) | Integrated business context (not separate sections) | docs/, code comments, metadata description |
| 4. Installation | Simple command + optional setup link | Actionable install command | Language-specific: pip, npm, cargo |
| 5. Documentation | Bulleted list of doc links | Only include links that exist | docs/quickstart.md, docs/architecture.md, adr/ |
| 6. Supporting Components (optional) | Dependency list with links | Skip for standalone projects | Docker Compose, K8s configs, related repos |
| 7. Contributing | Link or inline guidance | Link to CONTRIBUTING.md if exists | CONTRIBUTING.md, docs/contributing.md |
| 8. Bugs & Enhancements | Issue tracker link | Clear call-to-action | GitHub Issues from git remote, or prompt user |
Example (Prototype tier):
# Customer Churn Predictor
Early-stage prototype for predicting customer churn using transaction history.
## Description
The marketing team needs to identify customers at risk of churning to target retention campaigns effectively. This prototype implements a gradient boosting classifier trained on transaction and engagement data to predict churn probability.
## Installation
\`\`\`bash
pip install -e .
\`\`\`
## Documentation
- See notebooks in `notebooks/` for exploratory analysis
- Model card available in `docs/model-card.md`
## Contributing
This is an experimental prototype. For questions, contact the data science team.
## Bugs & Enhancements
Report issues via [GitHub Issues](https://github.com/USERNAME/churn-predictor/issues).
Badge Options Reference
Standard Personal badge format:
Badges should be wrapped in HTML comments for maintainability:
<!-- badges: start -->
[Badge 1]
[Badge 2]
...
<!-- badges: end -->
Available badge types (select based on project tier and applicability):
| Badge Type | Example | When to Use | Source |
|---|---|---|---|
| Version/Release | [](https://github.com/USERNAME/project/releases) |
All projects with releases | Git tags, pyproject.toml, package.json |
| Lifecycle | [](https://www.tidyverse.org/lifecycle/#experimental) |
All tiers (orange=prototype, yellow=mvp, green=production) | Project tier detection |
| Documentation | [](https://your-project-docs-url/) |
MVP/Production with published docs | Docs URL or relative link |
| Python Version | [](https://docs.python.org/3.12/) |
Python projects with version constraint | pyproject.toml, setup.py, .python-version |
| Code Style: black | [](https://github.com/psf/black) |
Python projects using black formatter | .pre-commit-config.yaml, pyproject.toml |
| Ruff | [](https://github.com/astral-sh/ruff) |
Python projects using ruff linter | .pre-commit-config.yaml, pyproject.toml |
| Pre-commit | [](https://github.com/pre-commit/pre-commit) |
Projects with pre-commit hooks | .pre-commit-config.yaml exists |
Lifecycle badge color scheme:
- Experimental/Prototype:
orange- Research, exploratory, not production-ready - MVP/Maturing:
yellow- Pilot deployment, active development - Stable/Production:
green- Production-ready, maintained
Tier-specific badge recommendations:
| Tier | Recommended Badges |
|---|---|
| Prototype | Optional: Version, Lifecycle (experimental-orange) |
| MVP | Version, Lifecycle (mvp-yellow), Docs |
| Production | Version, Lifecycle (stable-green), Docs, Python version (if applicable), Code style, Pre-commit |
Detection logic:
# Detect applicable badges from project files
badges = []
# Version/Release (always try to detect)
if has_git_tags or has_version_in_metadata:
badges.append(("Releases", version_number, releases_url))
# Lifecycle (required for all tiers)
tier = detect_project_tier() # prototype, mvp, production
lifecycle_colors = {"prototype": "orange", "mvp": "yellow", "production": "green"}
badges.append(("Lifecycle", tier, lifecycle_colors[tier]))
# Documentation (if docs exist)
if docs_url or has_docs_directory:
badges.append(("Docs", "latest", docs_url))
# Python-specific badges (only for Python projects)
if is_python_project:
if has_python_version_constraint:
badges.append(("Python version", python_version, python_docs_url))
if uses_black_formatter:
badges.append(("Code style: black", None, black_url))
if uses_ruff_linter:
badges.append(("Ruff", None, ruff_badge_url))
# Pre-commit (language-agnostic)
if has_precommit_config:
badges.append(("pre-commit", "enabled", precommit_url))
Example badge blocks by tier:
Prototype tier (minimal or no badges):
<!-- badges: start -->
[](https://www.tidyverse.org/lifecycle/#experimental)
<!-- badges: end -->
MVP tier (recommended badges):
<!-- badges: start -->
[](https://github.com/USERNAME/project/releases)
[](https://www.tidyverse.org/lifecycle/#maturing)
[](./docs/usage.md)
<!-- badges: end -->
Production tier (full badge set):
<!-- badges: start -->
[](https://github.com/USERNAME/project/releases)
[](https://www.tidyverse.org/lifecycle/#stable)
[](https://your-project-docs-url/)
[](https://docs.python.org/3.12/)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pre-commit/pre-commit)
<!-- badges: end -->
Important notes:
- Only include badges that are accurate and verifiable
- Don't add Python-specific badges to non-Python projects
- Badge URLs should link to meaningful resources (releases page, docs site, tool documentation)
- Use HTML comment wrappers for easy maintenance
Markdown Formatting Standards
Heading hierarchy:
#- Project title only##- Section headings (Description, Installation, etc.)###- Subsections (if needed, but keep minimal)
Code blocks:
- Always specify language: ```bash, ```python, ```json
- Use for installation commands, API examples
Links:
- Relative links for internal docs:
[Setup](docs/setup.md) - Absolute links for external resources:
[GitHub Issues](https://github.com/...) - Use descriptive link text, not "click here"
Lists:
- Use
-for unordered lists (consistent with style) - Use
1.for ordered lists (auto-numbering)
Context Extraction Patterns
Python projects - Read these files in order:
pyproject.toml-project.name,project.description,project.versionsetup.py-name,description,versionif no pyproject.tomlrequirements.txt- Dependencies list- Main module docstring - Business context
JavaScript projects - Read these files:
package.json-name,description,versionREADME.md- Existing content to preserve- Main file docstring - Business context
Documentation discovery:
- Architecture:
docs/architecture.md,*.drawio,*.mmd - ADRs:
adr/,docs/adr/ - Setup:
docs/setup.md,docs/installation.md,INSTALL.md - Contributing:
CONTRIBUTING.md,docs/contributing.md
Resources
Tier-Specific README Example (MVP)
# Feature Store API
RESTful API for serving customer features to ML models and analytics tools.
## Description
Data scientists need consistent, versioned access to customer features across projects, but currently extract features redundantly from raw data sources. This API provides a centralized feature store with versioning, caching, and real-time serving (<50ms p95).
## Installation
\`\`\`bash
pip install feature-store-client
\`\`\`
For local development, see [Setup Guide](docs/setup.md).
## Documentation
- [Quickstart Guide](docs/quickstart.md) - Get started in 5 minutes
- [API Reference](docs/api.md) - Complete endpoint documentation
- [Architecture](docs/architecture.md) - System design and data flow
- [ADRs](adr/) - Architecture Decision Records
## Supporting Components
- [Feature Pipeline](https://github.com/USERNAME/feature-pipeline) - Batch computation
- [Redis Cluster](internal-link) - Cache layer
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, submitting changes, and running tests.
## Bugs & Enhancements
Report bugs via [GitHub Issues](https://github.com/USERNAME/feature-store-api/issues).
Tier variations: Prototype skips badges/components; Production adds comprehensive docs (runbooks, monitoring, deployment guides).
Business context integration: See readme-standards skill "Before/After Examples" for good/bad business context patterns.
Edge Case Handling
No project metadata found:
- Prompt user: "What is the project name?"
- Prompt user: "Provide a one-sentence description"
No business context found:
- Prompt user: "What business problem does this solve?"
- Prompt user: "What solution does this project provide?"
- If user unsure: Generate technical description from code analysis
No documentation exists:
## Documentation
- See inline code documentation and docstrings for implementation details
- Architecture documentation coming soon
For questions, contact [team/person].
No CONTRIBUTING.md:
- Generate basic contributing section inline (see template above)
- Suggest creating CONTRIBUTING.md for mature projects
No tests detected:
- In Contributing section, note: "Please include tests with your contributions"
- Don't specify test command if none exists
Tier-Specific Variations
| Section | Prototype | MVP | Production |
|---|---|---|---|
| Badges | Optional (skip) | Include basic badges | Full badge set |
| Description | Brief (2-3 sentences) | Moderate (3-4 sentences) | Comprehensive (4-5 sentences) |
| Documentation Links | Minimal (notebooks, basic docs) | Moderate (quickstart, API, architecture) | Comprehensive (all resources) |
| Supporting Components | Usually none | May have 1-2 dependencies | Multiple service dependencies |
| Contributing | Basic inline guidance | Link to CONTRIBUTING.md | Full process documentation |
Link Validation
Before adding links to Documentation section:
- Verify file exists: Use file system check
- If missing: Don't add placeholder link
- Suggest creation: Note in validation report that docs should be created
Example validation logic:
docs_to_check = [
("Quickstart", "docs/quickstart.md"),
("Architecture", "docs/architecture.md"),
("ADRs", "adr/"),
]
valid_links = []
for name, path in docs_to_check:
if file_exists(path):
valid_links.append((name, path))
Remember: The goal is minimal, focused READMEs that serve as clear entry points. Link to detailed documentation rather than embedding everything inline.