Software Documentation Skill

Generate complete, professional documentation packages for any software project — APIs, web apps, mobile apps, e-commerce platforms, CLIs, microservices, and more.

This skill covers five documentation categories. Each project may need one or several. Always identify what's needed before writing.

Step 1: Gather Context

Before writing, determine:

• Project name, purpose, and type (API, web app, e-commerce, mobile, internal tool, etc.)
• Tech stack — language, framework, DB, infrastructure
• Project phase — in development, recently delivered, or being maintained?
• Audience — who will read each document (devs, client, QA, IT ops, legal)?
• Existing docs — what already exists? Avoid duplication.
• Delivery format — Markdown (default), PDF, Confluence/Notion export, HTML?

If the user shares a repo or codebase, explore it first and extract what you can before asking questions.

Step 2: Identify Documentation Category and Type

Category 1 — Technical Documentation (for developers)

Goal: any developer can understand, install, and extend the system without asking the original author.

Category 2 — User & Functional Documentation (for the client / end users)

Goal: explain what the system does and how to use it — no unnecessary technical jargon.

Category 3 — Quality & Testing Documentation (QA)

Goal: demonstrate that the software works correctly and is secure.

Category 4 — Operational & Support Documentation (IT / DevOps)

Goal: keep the system running and recoverable after incidents.

Category 5 — Legal & Closure Documentation

Goal: formally close the project and document rights, obligations, and support terms.

Step 3: Propose a Documentation Package

When the need is broad, propose a tailored package before writing:

Based on your project, I suggest generating:
✅ Category 1: README, Architecture Doc, API Reference
✅ Category 2: Admin User Manual, Glossary
✅ Category 3: Test Report, Traceability Matrix
✅ Category 4: Infrastructure Config, Known Issues Log
✅ Category 5: Acceptance Certificate, License Inventory

Which do you need first, or shall I start with the full set?

Prioritize by delivery urgency — closure docs first for finished projects, technical docs first for active development.

Step 4: Write the Documentation

General principles:

• Lead with what matters most: overview → setup → core usage → edge cases
• Copy-pasteable code blocks for all commands, configs, and examples
• Adapt language to audience: precise and technical for devs, clear and plain for end users
• Table of contents for any doc with more than 4 sections
• Warnings and notes for breaking changes, security considerations, irreversible actions
• Mermaid diagrams for architecture, flows, and data models — embed inline

Read the relevant reference file before drafting each document type.

Step 5: Present, Validate, and Iterate

• Present the draft in the conversation with clear section markers
• Flag assumptions explicitly: "Asumí que usas PostgreSQL — corrígeme si es diferente"
• Offer choices for structural decisions: "¿El glosario va dentro del manual o como documento separado?"
• Incorporate feedback and deliver a final .md file (or other requested format)

README Template (baseline for any project)

# Project Name

> One-sentence description of what it does and who it's for.

## Table of Contents
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

## Features
- Feature 1
- Feature 2

## Requirements
- Runtime: Node.js >= 18 / Python >= 3.10 / PHP >= 8.1
- Database: PostgreSQL 15+ / MySQL 8+ / MongoDB 6+

## Installation
\`\`\`bash
git clone https://github.com/org/project.git
cd project
npm install
cp .env.example .env
\`\`\`

## Quick Start
\`\`\`bash
npm run dev
\`\`\`

## Configuration
| Variable | Description | Required |
|---|---|---|
| `DATABASE_URL` | DB connection string | ✅ |
| `JWT_SECRET` | Auth token secret | ✅ |

## Documentation
- [API Reference](./docs/api.md)
- [Architecture](./docs/architecture.md)
- [User Manual](./docs/user-manual.md)

## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md)

## License
MIT

Mermaid Diagram Patterns

System architecture:

graph TD
  Client --> API_Gateway
  API_Gateway --> AuthService
  API_Gateway --> AppService
  AppService --> DB[(PostgreSQL)]
  AppService --> Cache[(Redis)]

Entity-Relationship:

erDiagram
  USER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : referenced_in

Deployment pipeline:

flowchart LR
  Dev -->|push| GitHub
  GitHub -->|CI/CD| DockerRegistry
  DockerRegistry -->|deploy| Production

Reference Files

Read the relevant file before drafting. Don't load all at once — only what the current document needs.

Quick Examples

"Documenta la arquitectura de mi app de microservicios en Go" → Read references/technical.md → produce SAD with component diagram, tech stack table, communication patterns

"Necesito el acta de entrega para firmar con el cliente" → Read references/legal-docs.md → produce formal acceptance certificate with scope summary, deliverables checklist, and signature blocks

"Genera el plan de pruebas para mi e-commerce" → Read references/qa-docs.md → produce test plan covering unit, integration, UAT, and security test cases

"Crea la documentación completa de mi API GraphQL" → Read references/api-docs.md → produce schema overview, query/mutation reference, auth flow, error handling guide

"Necesito el protocolo de backup para la app en producción" → Read references/ops-docs.md → produce backup protocol with schedule, retention policy, and restoration steps