Техническая документация: писать так, чтобы читали

# API Documentation

## Overview
This API provides functionality for user management.

## Endpoints
POST /api/users - Creates user
GET /api/users - Gets users

# Redis Cache Implementation

# Redis Cache Implementation

## Why
Database queries take 500ms. Users wait. We lose conversions.
Cache reduces this to 50ms.

## When to use
- Frequently accessed data
- Data that changes rarely
- Read-heavy workloads

// GetUser retrieves user by ID
func GetUser(id string) (*User, error)

// GetUser retrieves user by ID from cache or database.
// Returns ErrNotFound if user doesn't exist.
//
// Example:
//   user, err := GetUser("user-123")
//   if err == ErrNotFound {
//       return nil, fmt.Errorf("user not found")
//   }
func GetUser(id string) (*User, error)

# Feature Name

## Quick Start
Minimum code to get started (copy-paste ready)

## How It Works
High-level explanation

## API Reference
Detailed function descriptions

## Examples
Real-world scenarios

## Troubleshooting
Common problems and solutions

# Project Name

One sentence: what this does.

## Quick Start

```bash
git clone repo
make run

DATABASE_URL=postgres://...
REDIS_URL=redis://...

make test
make lint

### Полный README

```markdown
# Project Name

## What & Why

Problem: Users wait 5 seconds for page load
Solution: This service caches responses
Result: 100ms response time

## Quick Start

```bash
docker-compose up
curl http://localhost:8080/health

Client → API Gateway → Service → Database
              ↓
            Cache

git clone repo
cp .env.example .env
make install
make migrate
make run

POST /api/users
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "John"
}

{
  "id": "user-123",
  "email": "user@example.com"
}

make test

make lint
make fmt

docker build -t app .
docker push registry/app
kubectl apply -f k8s/

postgres://user:pass@host:5432/db?sslmode=disable

## Документирование кода

### Комментарии к функциям

Плохо:
```go
// Process processes data
func Process(data []byte) error

// Process validates and transforms incoming webhook data.
// Returns ErrInvalidFormat if data is malformed.
// Returns ErrDuplicate if webhook already processed.
//
// Process is idempotent - safe to call multiple times
// with same data.
func Process(data []byte) error

// Package cache provides Redis-based caching with automatic
// serialization and TTL management.
//
// Basic usage:
//
//   c := cache.New(redisClient)
//   c.Set(ctx, "key", value, 1*time.Hour)
//   var result MyType
//   c.Get(ctx, "key", &result)
//
// Cache handles serialization automatically using JSON.
// For custom serialization, implement cache.Marshaler.
package cache

// User represents authenticated user in the system.
// User data is cached for 1 hour after authentication.
type User struct {
    ID    string    // Unique identifier
    Email string    // Must be valid email
    Role  UserRole  // One of: admin, user, guest
}

// UserRole defines user permission level.
type UserRole string

const (
    RoleAdmin UserRole = "admin" // Full access
    RoleUser  UserRole = "user"  // Standard access
    RoleGuest UserRole = "guest" // Read-only
)

# ADR-001: Use Redis for Caching

## Status
Accepted

## Context
Database queries take 500ms average.
95% of queries are reads.
Data changes infrequently (hourly).

## Decision
Use Redis as cache layer between API and database.

## Consequences

### Positive
- 10x faster response time
- Reduced database load
- Better user experience

### Negative
- Additional infrastructure
- Cache invalidation complexity
- Potential stale data

## Alternatives Considered

### In-memory cache
- Pros: No external dependency
- Cons: Lost on restart, no sharing between instances

### Memcached
- Pros: Simple, fast
- Cons: No persistence, limited data structures

## Implementation
- Cache-aside pattern
- TTL: 1 hour
- Invalidation: on write operations

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    post:
      summary: Create user
      description: |
        Creates new user account.
        Email must be unique.
        Password must be 8+ characters.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  minLength: 8
                  example: SecurePass123
      responses:
        201:
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        400:
          description: Invalid input
        409:
          description: Email already exists

## Create User

```bash
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123"
  }'

{
  "id": "user-123",
  "email": "user@example.com",
  "created_at": "2024-01-22T10:00:00Z"
}

{
  "error": "invalid_email",
  "message": "Email format is invalid"
}

## Runbook для операций

```markdown
# Service Runbook

## Health Checks

### Application
```bash
curl http://localhost:8080/health

psql $DATABASE_URL -c "SELECT 1"

redis-cli -u $REDIS_URL ping

go tool pprof http://localhost:8080/debug/pprof/profile

go tool pprof http://localhost:8080/debug/pprof/heap

kubectl set image deployment/app app=registry/app:v1.2.3
kubectl rollout status deployment/app

kubectl rollout undo deployment/app

## Changelog

```markdown
# Changelog

## [1.2.0] - 2024-01-22

### Added
- User authentication with JWT
- Rate limiting per user
- Metrics endpoint

### Changed
- Improved error messages
- Updated dependencies

### Fixed
- Race condition in cache
- Memory leak in websocket handler

### Security
- Fixed SQL injection in search
- Updated crypto library

## [1.1.0] - 2024-01-15

...

//go:generate go run github.com/swaggo/swag/cmd/swag init

// @title User API
// @version 1.0
// @description User management service
// @host localhost:8080
// @BasePath /api
func main() {
    // ...
}

#!/bin/bash
# check-docs.sh

# Check README exists
if [ ! -f README.md ]; then
    echo "README.md missing"
    exit 1
fi

# Check all public functions documented
undocumented=$(go doc -all | grep "^func" | grep -v "//")
if [ -n "$undocumented" ]; then
    echo "Undocumented functions:"
    echo "$undocumented"
    exit 1
fi

# Check links in markdown
markdown-link-check README.md