Docs

Documentación — Reglas y Convenciones

---

1. Filosofía

1. Documentación como código — Los docs viven en el repo, se versionan, se revisan en PRs y siguen las mismas convenciones que el código.
2. Valor sobre cantidad — Cada documento responde a una pregunta concreta. Sin relleno, sin contenido duplicado, sin documentación por documentar.
3. Legibilidad — El lenguaje debe ser claro, directo y adaptado a la audiencia. Priorizar ejemplos sobre descripciones abstractas.
4. Mantenibilidad — Los docs se mantienen junto al código. Si cambia la API, cambia la documentación en el mismo PR.
5. Progressive disclosure — Información de lo general a lo específico. README primero, luego guías, luego API reference.

---

2. Estructura de Documentos

README.md (esencial)

````markdown

Nombre del Proyecto

Descripción breve: qué hace, para quién, por qué existe.

Instalación

npm install mi-paquete

````

Uso rápido

import { algo } from "mi-paquete";
algo();

API

función(opciones)

Descripción de la función, parámetros, valor de retorno.

| Parámetro | Tipo | Default | Descripción | | ---------- | -------- | ------- | ------------------ | | opciones | Object | {} | Opciones de Config |

Contribuir

Ver [CONTRIBUTING.md](./CONTRIBUTING.md)

Licencia

MIT © 2026

````text

Componentes de un buen README

| Sección | Obligatorio | Propósito | | --------------- | ----------- | ---------------------------------- | | Título + badges | ✅ | Identidad y estado del proyecto | | Descripción | ✅ | Propósito y audiencia | | Instalación | ✅ | Primeros pasos | | Uso rápido | ✅ | Ejemplo mínimo funcional | | API | ⚠️ condicional | Referencia detallada | | Contribuir | ⚠️ condicional | Guía para colaboradores | | Licencia | ✅ | Términos de uso | | Changelog | ⚠️ condicional | Historial de cambios |

CONTRIBUTING.md

# Contribuyendo al proyecto

## Proceso

1. Fork el repo
2. Crea una rama: `git checkout -b feature/42-nombre`
3. Haz cambios en commits atómicos
4. Asegúrate de que los tests pasen
5. Abre un Pull Request

## Convenciones

- Commits: [Conventional Commits](../git/SKILL.md)
- Código: sigue el estilo del proyecto
- Tests: incluye tests para nuevas funcionalidades
- Documentación: actualiza docs si cambia la API
````

### CODE_OF_CONDUCT.md

```markdown
# Código de Conducta

## Compromiso

Nos comprometemos a hacer de la participación en este proyecto
una experiencia libre de acoso para todos.

## Comportamiento esperado

- Usar lenguaje inclusivo y respetuoso
- Aceptar críticas constructivas
- Enfocarse en lo que es mejor para la comunidad

## Comportamiento inaceptable

- Comentarios sexuales o violentos
- Trolling, insultos, ataques personales
- Acoso público o privado

## Aplicación

Reportar incidentes a [email].

---

3. Markdown

Sintaxis esencial

# H1

## H2

### H3

**negrita** _cursiva_ `código inline`

[link](https://ejemplo.com)

- Lista no ordenada
- Item

1. Lista ordenada
2. Item

> Cita

` ``js
console.log("código bloque"); ` ``

| Tabla | Columna 2 |
| ----- | --------- |
| Dato  | Dato      |

---

Reglas de formato

• Una línea en blanco antes/después de headings
• Una línea en blanco antes/después de listas y bloques de código
• Líneas máximo 80 caracteres en párrafos (no aplica a tablas ni bloques de código)
• Sin espacios al final de línea
• Listas con - (no *)
• Bloques de código siempre con lenguaje especificado

Frontmatter YAML

---
title: Título del documento
description: Descripción breve
date: 2026-07-15
author: Nombre
---

Admonitions (soportado por varios renderers)

> **Nota:** Información adicional importante.

> **Advertencia:** Esto puede causar problemas.

> **Peligro:** Esto es crítico.

Links internos

[Ver sección](#sección)
[Referencia a otro documento](./CONTRIBUTING.md)
[Link absoluto](/docs/api.md)

---

4. Documentación de API

JSDoc

/**
 * Calcula el total con impuestos.
 *
 * @param {number} subtotal - Monto sin impuestos
 * @param {number} [taxRate=0.16] - Tasa de impuesto (default 16%)
 * @returns {number} Total con impuestos incluidos
 * @throws {TypeError} Si subtotal no es un número
 *
 * @example
 * const total = calcularTotal(100, 0.16)
 * // → 116
 */
export function calcularTotal(subtotal, taxRate = 0.16) {
  if (typeof subtotal !== "number") {
    throw new TypeError("subtotal debe ser un número");
  }
  return subtotal * (1 + taxRate);
}

Tags JSDoc esenciales

| Tag | Uso | | ------------- | ----------------------------------------- | | @param | Descripción de parámetro (+ tipo) | | @returns | Valor de retorno (+ tipo) | | @throws | Error que puede lanzar | | @example | Ejemplo de uso (seguido de bloque código) | | @deprecated | Marca como obsoleto | | @see | Referencia a otro elemento | | @typedef | Definición de tipo personalizado | | @property | Propiedad de un tipo | | @template | Parámetro genérico (TypeScript) |

/**
 * @typedef {Object} User
 * @property {number} id - Identificador único
 * @property {string} name - Nombre completo
 * @property {string} email - Correo electrónico
 */

/**
 * @template T
 * @param {T} item
 * @returns {T}
 */
function identity(item) {
  return item;
}

TypeDoc

interface Config {
  /** Puerto del servidor */
  port: number;
  /** Host donde escuchar */
  host: string;
}

/**
 * Inicia el servidor con la configuración dada.
 *
 * @param config - Opciones de configuración
 * @returns Una promesa que resuelve cuando el servidor inicia
 */
async function startServer(config: Config): Promise;

---

5. Changelog

Formato (Keep a Changelog)

# Changelog

## [1.2.0] - 2026-07-15

### Added

- Nueva funcionalidad X
- Soporte para Y

### Changed

- Mejorada la performance de Z
- Actualizada dependencia A a v2

### Deprecated

- Función `foo()` será eliminada en v2

### Removed

- Eliminado soporte para navegadores antiguos

### Fixed

- Corregido bug en login (#42)

### Security

- Parcheada vulnerabilidad CVE-2026-XXXX

## [1.1.0] - 2026-06-01

### Added

- Feature menor

## [1.0.0] - 2026-01-15

### Added

- Release inicial

Reglas del Changelog

• Mantenerlo manual — No generar automáticamente desde commits (el resultado es ruidoso)
• Agrupar por tipo — Added, Changed, Deprecated, Removed, Fixed, Security
• Referenciar issues/PRs — (#42) al final de cada línea
• Fecha en ISO 8601 — YYYY-MM-DD
• SemVer — La versión del changelog debe coincidir con los tags de git
• Unreleased section — Mantener una sección [Unreleased] en desarrollo

---

6. Documentación Técnica

Guías vs Referencia

| Tipo | Propósito | Audiencia | Formato | | -------------- | ----------------------------------------- | ------------------ | ---------------- | | Guía | Cómo lograr un objetivo paso a paso | Usuarios nuevos | Tutorial, how-to | | Ref | Descripción completa de API, config, etc. | Usuarios avanzados | Reference | | Conceptual | Explicación de conceptos y arquitectura | Todos | Explicación |

Ejemplo: Guía de inicio rápido

````markdown

Guía: Configurar autenticación

En esta guía agregarás autenticación por email/password.

Prerrequisitos

• Node.js 22+
• Proyecto inicializado

Paso 1: Instalar dependencias

npm install @auth/core

````

Paso 2: Configurar proveedor

import { Auth } from "@auth/core";

const auth = new Auth({
  provider: "credentials",
  // ...
});

Ejemplo: Documentación conceptual

# Arquitectura del sistema

## Capas

1. **Presentación** — Componentes UI (React/Vanilla)
2. **Lógica de negocio** — Hooks, servicios, utils
3. **Acceso a datos** — API calls, caché, almacenamiento local

## Flujo de datos

[Diagrama de flujo o descripción textual]

Los datos viajan de la capa de datos a la presentación
a través de hooks personalizados que manejan loading, error y éxito.

---

7. Diagramas (Mermaid)

Incorporar diagramas en los docs usando Mermaid (soportado por GitHub, GitLab y renderers MD):

flowchart TD
    A[Inicio] --> B{¿Autenticado?}
    B -->|Sí| C[Dashboard]
    B -->|No| D[Login]
    D --> C

sequenceDiagram
    User->>API: POST /login
    API->>DB: Verificar credenciales
    DB-->>API: Usuario válido
    API-->>User: Token JWT

graph LR
    A[HTML] --> B[CSS]
    A --> C[JavaScript]
    B --> D[DOM]
    C --> D

Tipos de diagrama recomendados

| Tipo | Para qué usar | | ----------------- | ----------------------------------------- | | flowchart | Flujos de proceso, decisiones, pipelines | | sequenceDiagram | Interacciones entre componentes/servicios | | classDiagram | Estructuras de clases y relaciones | | stateDiagram | Estados de un componente o proceso | | graph | Relaciones generales entre entidades | | gantt | Cronogramas y planificación |

---

8. Documentación de Componentes (Frontend)

````markdown

Componente: Button

Botón reutilizable con variantes visuales y estados.

Propiedades

| Prop | Tipo | Default | Descripción | | ---------- | ------------------------------------- | ----------- | -------------------- | | variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Estilo visual | | size | 'sm' \| 'md' \| 'lg' | 'md' | Tamaño del botón | | disabled | boolean | false | Estado deshabilitado | | loading | boolean | false | Muestra spinner | | onClick | () => void | — | Handler de click |

Estados

| Estado | Comportamiento | | ------------ | ---------------------------------------- | | Normal | Estilo según variant | | Hover | Darken 10% del color base | | Active | Darken 20% del color base | | Disabled | Opacidad 50%, sin hover, sin click | | Loading | Muestra spinner, deshabilita interacción | | Focus | Outline visible (accesibilidad) |

Ejemplos

Botón primario

Guardar

````

Botón con loading

   Cargando...

---

9. Herramientas

TypeDoc Tools

# Instalación
npm install -D typedoc

# Config (typedoc.json)
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "excludePrivate": true,
  "excludeProtected": true,
  "theme": "default"
}

# Generar
npx typedoc

JSDoc Tools

# Generar documentación desde JSDoc
npm install -D jsdoc

# Config (jsdoc.json)
{
  "source": { "include": ["src"] },
  "opts": { "destination": "docs/api" }
}

# Generar
npx jsdoc -c jsdoc.json

Vitepress (documentación de proyecto)

npm install -D vitepress

# Estructura
docs/
  .vitepress/
    config.js
  index.md
  guide/
    getting-started.md
  api/
    reference.md

# Config (.vitepress/config.js)
export default {
  title: 'Mi Proyecto',
  description: 'Documentación del proyecto',
  themeConfig: {
    nav: [
      { text: 'Guía', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ],
    sidebar: [
      { text: 'Introducción', link: '/guide/' }
    ]
  }
}

Markdown lint

npm install -D markdownlint-cli

# Config (.markdownlint.json)
{
  "MD013": { "line_length": 80 },
  "MD033": false,
  "MD041": false
}

# Ejecutar
npx markdownlint '**/*.md' --ignore node_modules

---

10. Documentación en PRs

Descripción de PR

## Descripción

## Cambios principales

- Agrega endpoint de login
- Actualiza documentación de API
- Corrige tipografía en README

## Documentación relacionada

- [ ] README actualizado
- [ ] JSDoc agregado a funciones nuevas
- [ ] Changelog actualizado
- [ ] API docs actualizadas

## Breaking changes

## Closes

Closes #42

Reglas para docs en PRs

• README: Actualizar si cambia instalación, uso o API pública
• JSDoc/TypeDoc: Toda función pública debe estar documentada
• Changelog: Agregar entrada en [Unreleased] con tipo correspondiente
• API docs: Si se agrega/modifica un endpoint, actualizar la referencia

---

11. Estilo de Escritura

Lenguaje

• Español para proyectos dirigidos a hispanohablantes
• Inglés para proyectos open-source internacionales (por defecto en la skill git)
• No mezclar idiomas en un mismo documento
• Tú (informal) en lugar de "usted" o "el usuario"

Convenciones

# ✅ Bueno

Haz clic en Guardar para continuar.

# ❌ Malo

El usuario debería hacer clic en el botón de Guardar para continuar.

# ✅ Bueno

Crea un archivo `.env` con las siguientes variables:

# ❌ Malo

Deberías crear un archivo .env con las siguientes variables de entorno.

Voz activa

# ✅ Bueno

El hook `useAuth` retorna el usuario autenticado.

# ❌ Malo

El usuario autenticado es retornado por el hook `useAuth`.

Ejemplos ejecutables

Todos los ejemplos de código deben:

• Poder copiarse y pegarse para funcionar (sin placeholders no obvios)
• Incluir imports completos (no fragmentos)
• Tener comentarios explicativos solo si es necesario

---

12. Documentación de Configuración

````markdown

Configuración

Variables de entorno

| Variable | Default | Obligatoria | Descripción | | -------------- | ------------- | ----------- | -------------------- | | DATABASE_URL | — | ✅ | URL de conexión a DB | | PORT | 3000 | ❌ | Puerto del servidor | | NODE_ENV | development | ❌ | Entorno de ejecución |

Archivo de configuración

{
  "api": {
    "baseUrl": "https://api.ejemplo.com",
    "timeout": 5000
  },
  "ui": {
    "theme": "dark",
    "language": "es"
  }
}

````

Ejemplo de archivo .env.example

# Copiar a .env y completar valores
DATABASE_URL=postgresql://user:pass@localhost:5432/db
PORT=3000
API_KEY=tu-api-key

---

13. Prohibiciones

• ❌ NO documentar lo obvio (// suma dos números en function sum(a, b))
• ❌ No dejar secciones TODO/FIXME en docs publicados
• ❌ No usar click here como link text
• ❌ No mezclar inglés y español en el mismo documento
• ❌ No documentar implementación privada (solo API pública)
• ❌ No generar changelogs automatizados sin editar (son ruidosos)
• ❌ No asumir conocimiento previo del lector sin contexto
• ❌ No incluir información sensible (API keys, passwords) en ejemplos
• ❌ No usar `` o HTML en Markdown salvo casos justificados
• ❌ No dejar bloques de código sin lenguaje especificado
• ❌ No docs desactualizados — si el código cambia, los docs cambian

---

14. Referencias

> Nota: Para commits y PRs, ver [Git](../git/SKILL.md)

---

Última actualización: 2026-07

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 14BryanEspinoza
• Source: 14BryanEspinoza/agent-stack
• License: MIT

Install and usage instructions live in the source repository linked above.