353 lines
14 KiB
Markdown
353 lines
14 KiB
Markdown
---
|
|
title: README Authoring
|
|
description: Best practices and templates for generating README sections following standards
|
|
tags: [readme, documentation, templates, authoring]
|
|
---
|
|
|
|
# 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**:
|
|
|
|
1. **Project Title & One-Liner** - Name + 1-2 sentence description
|
|
2. **Badges Block** *(optional)* - Version, lifecycle, docs, code style
|
|
3. **Short Description** - Business problem/solution + core functionality (3-5 sentences)
|
|
4. **Installation** - Simple command or link to detailed setup
|
|
5. **Documentation** - Links to key resources (architecture, ADRs, guides)
|
|
6. **Supporting Components** *(optional)* - Related repos/services
|
|
7. **Contributing** - How to contribute or link to CONTRIBUTING.md
|
|
8. **Bugs & Enhancements** - Issue tracker link
|
|
|
|
### Section Generation Reference
|
|
|
|
| Section | Template | Key Requirements | Common Sources |
|
|
|---------|----------|------------------|----------------|
|
|
| **1. Title & One-Liner** | `# {Name}`<br>`{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)**:
|
|
```markdown
|
|
# 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:
|
|
|
|
```markdown
|
|
<!-- 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**:
|
|
|
|
```python
|
|
# 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):
|
|
```markdown
|
|
<!-- badges: start -->
|
|
[](https://www.tidyverse.org/lifecycle/#experimental)
|
|
<!-- badges: end -->
|
|
```
|
|
|
|
**MVP tier** (recommended badges):
|
|
```markdown
|
|
<!-- badges: start -->
|
|
[](https://github.com/USERNAME/project/releases)
|
|
[](https://www.tidyverse.org/lifecycle/#maturing)
|
|
[](./docs/usage.md)
|
|
<!-- badges: end -->
|
|
```
|
|
|
|
**Production tier** (full badge set):
|
|
```markdown
|
|
<!-- 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:
|
|
1. `pyproject.toml` - `project.name`, `project.description`, `project.version`
|
|
2. `setup.py` - `name`, `description`, `version` if no pyproject.toml
|
|
3. `requirements.txt` - Dependencies list
|
|
4. Main module docstring - Business context
|
|
|
|
**JavaScript projects** - Read these files:
|
|
1. `package.json` - `name`, `description`, `version`
|
|
2. `README.md` - Existing content to preserve
|
|
3. 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)
|
|
|
|
```markdown
|
|
# 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**:
|
|
```markdown
|
|
## 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:
|
|
|
|
1. **Verify file exists**: Use file system check
|
|
2. **If missing**: Don't add placeholder link
|
|
3. **Suggest creation**: Note in validation report that docs should be created
|
|
|
|
**Example validation logic**:
|
|
```python
|
|
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.
|