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 # Edit .env with your configuration -
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
/**
* Brief description of what the function does.
*
* @param paramName - Description of parameter
* @returns Description of return value
* @throws ErrorType - When this error occurs
*
* @example
* const result = functionName(input);
*/
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