Método de documentación

Última actualización: 24-01-2026 07:11 PM

Método de documentación (pDOCS)

Propósito: definir un método único para documentar cualquier proyecto de forma que, al abrir un chat o retomar semanas después, sea posible entrar en contexto y ejecutar sin reconstruir mentalmente la historia.

Principios

Retoma rápida > belleza del texto: el texto existe para entender y actuar, no para sonar bien.
Simple por defecto, detalle por necesidad: podemos escribir largo y profundo sin miedo cuando el detalle reduce ambigüedad, evita errores o ahorra retrabajo. La regla no es “corto”, es “lo necesario”.
Monolito primero (y con intención): el Documento Monolito no es un borrador “feo” ni algo temporal; es la base del proyecto. En muchos proyectos será suficiente quedarse con los monolitos (y uno que otro documento separado). Se divide solo cuando sea necesario.
Consistencia: mismos encabezados, marcas y orden para entrar automáticamente en “modo documentación”.

Estructura del método

Este método se compone de:

Intro (muy corto): guía de lectura y orientación.
Documento Monolito (entrada única):
- Contexto
- Modularidad (incluye diagramas cuando aporten)
- Backlog

Nota: los diagramas son transversales. Se usan donde hagan falta (Contexto, Modularidad o Backlog). Si el proyecto necesita un estándar, se referencia una guía de diagramas (por ejemplo: diagrama visual + representación legible para LLM).

Checklist de arranque (cuando vamos a documentar un proyecto)

Cuando me compartas el link del Intro o me digas “documentemos X”, idealmente me das:

Link al repo (y rama principal).
Objetivo del proyecto (1–3 frases).
Filosofía/criterio: qué estás optimizando y por qué.
Stack/tecnologías clave (y plataforma objetivo).
Estado actual + próximo objetivo (hito).

1) Intro

Qué es

Documento mínimo que responde: “¿Qué es este proyecto y qué debo leer para entenderlo?”

Qué contiene (y qué NO)

Contiene:

Una sola frase de definición del proyecto (derivada del documento de Contexto).
La lista de documentos obligatorios a leer (con links internos).
Opcional: atajos a secciones internas usando anchors estables (solo si realmente aportan navegación).

No contiene:

Decisiones, controles, plataforma, arquitectura, implementación, backlog, ni detalles técnicos. Eso vive en Contexto / Modularidad / Backlog (o los documentos equivalentes del proyecto).

Para qué sirve

Ser el punto de entrada del proyecto sin re-explicar contexto en cada conversación.
Garantizar que cualquier persona o asistente lea la documentación completa desde una sola página.
Mantener un “landing” estable y barato de mantener.

Links y anchors (regla operativa)

Los enlaces deben ser rutas internas del sitio (ej.: /proyectos/<proyecto>/<seccion>/.../), no URLs completas.
Para links a secciones internas, usar anchors manuales y estables cuando sea necesario:

<a id="camara"></a>
## 6) Cámara

y linkear como .../#camara.

Convención para id:

kebab-case, sin tildes, sin símbolos raros: camara, input-system, deploy-webgl.
Un id no se cambia salvo decisión explícita (porque rompe enlaces).

Mantenimiento

Actualizar el Intro solo si:

cambian las rutas/nombres de documentos, o
se agregan/eliminan documentos de lectura obligatoria, o
se añaden/ajustan atajos de navegación (anchors).

Regla de permanencia (no se divide)

Este documento no se divide en subdocumentos.

Su función es ser un índice/landing único y estable: puede crecer si hace falta (más links, más atajos), pero siempre permanece como una sola página.

Si hay que dividir algo, se divide el contenido del proyecto (Contexto / Modularidad / Backlog o equivalentes), no el Intro.

2.1) Contexto

Qué es

La parte destinada a que el lector entre en situación completa sin que tengas que re-explicar:

Por qué existe el proyecto.
Qué se busca (intención / filosofía).
Con qué se construye (ficha técnica / stack).
Cómo interpretar la documentación (lenguaje/etiquetas/estado de decisiones), si aplica.

Para qué sirve

Reemplazar la re-explicación recurrente al iniciar un chat.
Hacer explícito lo que normalmente queda en tu cabeza: intención, criterio, restricciones.
Mantener estable la base: es típicamente el documento más estable de los tres.

Contenido mínimo obligatorio (sí o sí)

Filosofía / idea (profunda, no “descripción”)
- Debe escribirse con suficiente detalle para que se sienta el peso de la intención.
- Se construye a partir de preguntas hasta que quede claro el “por qué” y el “para qué”.
- Puede y debe ser varios párrafos si eso mejora comprensión.
Ficha técnica
- Stack principal (lenguajes, frameworks, motor, libs clave).
- Plataformas objetivo.
- Requisitos/restricciones relevantes.
- (Opcional) Entorno/herramientas si afectan ejecución: IDE, build, CI, etc.

Contenido recomendado (candidato a incluir)

Esta lista está intencionalmente como “recomendado” para decidir qué te aporta. No todo aplica a todo proyecto.

Alcance y no-alcance (qué entra y qué no entra).
Criterios de calidad (performance, maintainability, UX, etc.).
Convenciones de trabajo (cómo trabajamos el proyecto): branching, naming, versionado, CI, herramientas, etc. Solo si impacta decisiones o ejecución.
Glosario (si hay términos internos).
Decisiones / criterios cerrados (cuando el proyecto lo amerite):
- Qué se cerró, alternativas consideradas, motivo real, impacto, estado, fecha.

Marcas/etiquetas recomendadas

[Pendiente]: falta una respuesta concreta.
[Por confirmar]: se está operando con X por ahora, hasta confirmar Y (no implica que esté “mal”; solo no está verificado).
[Decisión]: criterio cerrado (qué se eligió, por qué, impacto, fecha).

2.2) Modularidad

Qué es

La parte que documenta todas las partes técnicas del proyecto: componentes, subsistemas, servicios, carpetas, pipelines, herramientas, integraciones, etc.

Para qué sirve

Ser la “radiografía” del proyecto: qué existe, dónde vive y cómo se conecta.
Registrar cómo se implementó lo que ya quedó cerrado.
Permitir separar después: cuando un módulo crece o es crítico, se extrae a documento dedicado.

Por qué “Modularidad”

Se asume que el proyecto se construye como sistema modular, donde cada parte tiene responsabilidad y límites claros. Esta sección fuerza a pensar el proyecto como piezas que se conectan, se separan y se documentan con límites claros.

Cómo se construye (plantilla base)

Mapa general (lista o diagrama simple).
Para cada módulo:
- Responsabilidad.
- Entradas/salidas (APIs, eventos, archivos, datos).
- Dependencias.
- Puntos críticos / riesgos.
- Cómo correr/probar (si aplica).

Diagramas

Se permiten cuando:

Aclaran un flujo crítico.
Reducen ambigüedad entre módulos.
Explican dependencias.

No se usan por decoración.

2.3) Backlog (por ahora)

Qué es

La parte “viva” que lista lo que falta por hacer y lo que hay que corregir (pendientes):

Lo que tú quieres hacer.
Lo que tú piensas hacer.
Y también lo que debe hacerse según lo que se detecta al analizar Modularidad (deuda, inconsistencias, riesgos).

Para qué sirve

Convertir diagnóstico en acción.
Registrar pendientes y correcciones que no deben perderse.
Asegurar que el asistente no solo ejecuta órdenes, sino que también señala problemas y los convierte en tareas rastreables.

Cómo se mantiene (regla clave)

El Backlog debería tender a hacerse más corto con el tiempo.
Lo terminado se mueve a Modularidad (ya explicado como parte cerrada).
El Backlog no es un cementerio infinito: es un motor de cierre.

Plantilla base

Hito actual / objetivo próximo.
Prioridades (máx. 5).
Pendientes (ordenados).
Correcciones sugeridas (detectadas por el asistente).
Riesgos y mitigación.
Definition of Done del hito.

Nota sobre el nombre

Por ahora se usa Backlog porque describe bien la intención: una lista de pendientes que se cierra y se migra a Modularidad. El nombre puede cambiar después si aparece una alternativa en español que encaje mejor.

“Modo documentación” (cómo trabajamos tú y yo)

Cuando me digas “documentemos el proyecto X”, yo:

Creo o valido Intro + Monolito.
Construyo primero Contexto (mínimo obligatorio + lo que aporte; filosofía con suficiente profundidad).
Luego documento Modularidad (mapa + descripciones completas).
Finalmente construyo Backlog (pendientes tuyos + correcciones detectadas).
Todo lo incierto se marca como [Pendiente] o [Por confirmar].

Pendientes abiertos de este método (para iterar aquí mismo)

Definir Formato de escritura (estilo): títulos, densidad de texto, uso de tablas, cuándo usar bullets vs párrafos, etc.
Definir o referenciar una Guía de diagramas (transversal): estándar visual y representación legible para LLM (por ejemplo: D2 para lo visual + Mermaid/alternativa legible).
Afinar el formato recomendado de Contexto (qué entra siempre vs opcional), sin perder profundidad en la filosofía.