# Documentation Writer

> Write clear, comprehensive technical documentation. Covers README files, API docs, tutorials, architecture guides, and documentation systems.

- Skill: `atulpurohit/documentation-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atulpurohit/documentation-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atulpurohit/documentation-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: AtulPurohit (https://skillmd.com/u/atulpurohit)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/atulpurohit/documentation-writer

---


# Documentation Writer

## Purpose
Create documentation that developers actually read and use, reducing friction and support burden.

## Documentation Types

### 1️⃣ README Best Practices
```markdown
# Project Name

> One-line description of what this project does.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](...)
[![npm version](https://badge.fury.io/js/package-name.svg)](...)

## What is this?
[2-3 sentence explanation for someone who has never heard of this]

## Quick Start
[The absolute minimum to get something running in < 5 minutes]

```bash
npm install package-name
```

```javascript
import { feature } from 'package-name';
const result = feature('hello');
```

## Features
- ✅ Feature one (benefit, not just name)
- ✅ Feature two

## Installation
[Detailed installation including prerequisites]

## Usage
[Common use cases with complete examples]

## API Reference
[Complete API documentation or link to it]

## Contributing
[How to contribute, run tests, submit PRs]

## License
MIT
```

### 2️⃣ API Documentation (OpenAPI + Examples)
Every endpoint should document:
- What it does (human readable)
- Request: URL, method, headers, body (with schema and examples)
- Response: status codes, body (with schema and examples)
- Errors: all possible error codes and messages
- Authentication: what's required
- Rate limits: if applicable
- Code examples in multiple languages (curl, JS, Python)

### 3️⃣ Architecture Documentation
Use ADRs (Architecture Decision Records):
```markdown
# ADR-001: Use PostgreSQL for Primary Database

## Status: Accepted

## Context
We need to store user profiles, orders, and analytics data.
The data has complex relationships and requires ACID transactions.

## Decision
Use PostgreSQL 16 as our primary database.

## Rationale
- Mature, battle-tested for 20+ years
- Full ACID compliance for financial data
- JSON support for flexible metadata
- Team has deep PostgreSQL expertise
- Excellent tooling (pgAdmin, migrations, backups)

## Alternatives Considered
- MySQL: Similar capabilities, less advanced features
- MongoDB: Better for unstructured data, but our data is relational

## Consequences
✅ Strong consistency and reliability
✅ Complex queries with JOINs
❌ Harder to scale horizontally than NoSQL
❌ Schema migrations require planning
```

## Outputs
1. README template with all sections
2. API documentation in OpenAPI format
3. Architecture decision records
4. Onboarding guide for new developers
5. Runbook / operations guide