| name | documentation-expert |
| description | Documentation expert for writing professional README.md files and project documentation. Use this skill when creating or updating README files, writing API documentation, or generating project documentation with modern layout, tech stack badges, flowcharts, and comprehensive structure. Triggers on requests for (1) README creation/updates, (2) Project documentation, (3) API reference documentation, (4) Architecture documentation, (5) Contributing guides. |
Documentation Expert
Expert in writing clean, modern, and professional project documentation following best practices.
README Structure
Organize README files with the following sections:
| Section | Purpose |
|---|
| Title + One-liner | What is this? |
| Quick Start | Running in <5 min |
| Features | What can I do? |
| Configuration | How to customize |
| API Reference | Link to detailed docs |
| Contributing | How to help |
| License | Legal |
Tech Stack Badges
Use shields.io badges for a modern, professional look:
Badge format: https://img.shields.io/badge/{LABEL}-{MESSAGE}-{COLOR}?style=flat&logo={LOGO}&logoColor=white
README Template
# Project Name
Brief one-line description of what this project does.
## Quick Start
[Minimum steps to run the project]
### Prerequisites
- Python 3.12+
- uv package manager
### Installation
1. Clone the repository
```bash
git clone https://github.com/user/repo.git
cd repo
-
Install dependencies
uv sync
-
Set up environment variables
cp .env.example .env
-
Run the application
uv run python src/main.py
Features
- Feature 1: Description
- Feature 2: Description
- Feature 3: Description
Configuration
| Variable | Description | Default |
|---|
PORT | Server port | 8000 |
DEBUG | Enable debug mode | false |
DATABASE_URL | Database connection string | - |
Project Structure
[Brief overview of key directories and files]
Documentation
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
License
MIT
## Flowchart Guidelines
Use Mermaid diagrams to visualize workflows. Place flowcharts after explaining the concept they represent.
### Application Flow Example
```mermaid
flowchart TD
A[User Request] --> B{API Gateway}
B --> C[FastAPI Backend]
C --> D[(SQLite Database)]
C --> E[External APIs]
E --> F[Process Data]
F --> G[Return Response]
Data Pipeline Example
flowchart LR
A[Data Source] --> B[Fetch]
B --> C[Transform]
C --> D[Store]
D --> E[Serve]
API Documentation Template
Per-Endpoint Format
## GET /api/resource/:id
Get a resource by ID.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | Resource ID |
**Response:**
- `200`: Resource object
- `404`: Resource not found
**Example:**
Request:
```bash
curl -X GET http://localhost:8000/api/resource/123
Response:
{
"id": "123",
"name": "Example",
"created_at": "2025-01-01T00:00:00Z"
}
## Code Comment Guidelines
### When to Comment
| Comment | Do Not Comment |
|---------|----------------|
| Why (business logic) | What (obvious) |
| Complex algorithms | Every line |
| Non-obvious behavior | Self-explanatory code |
| API contracts | Implementation details |
### Python Docstring Template
```python
def function_name(param: str) -> dict:
"""
Brief description of what the function does.
Args:
param: Description of parameter
Returns:
Description of return value
Raises:
ValueError: When this error occurs
Example:
>>> result = function_name("input")
"""
TypeScript JSDoc Template
Writing Principles
| Principle | Why |
|---|
| Scannable | Headers, lists, tables |
| Examples first | Show, do not just tell |
| Progressive detail | Simple to Complex |
| Up to date | Outdated = misleading |
Style Rules
- No emojis in documentation
- Use headers to organize content hierarchically
- Use tables for structured data (configuration, parameters)
- Use code blocks with language hints for syntax highlighting
- Use Mermaid diagrams for workflows and architecture
- Keep lines short for readability
- Use absolute paths for file references within the repository
