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)

# Nombre del Proyecto

<!-- Badges: estado, version, license, CI, coverage -->

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

## Instalación

```bash
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

Licencia

MIT © 2026

### 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

```markdown
# 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

# 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)
![imagen](img.png)

- 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<void>;

---

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

# 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

```bash
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)

# 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

```html
<button class="btn btn--primary">Guardar</button>
```

Botón con loading

<button class="btn btn--primary" disabled aria-busy="true">
  <span class="spinner"></span> Cargando...
</button>

---

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

<!-- Qué hace este PR, por qué es necesario -->

## 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

<!-- Si aplica, describir el cambio y cómo migrar -->

## 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

# 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

```json
{
  "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 <blink> 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

---

Última actualización: 2026-07