> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need. # Documentar en este repositorio Esta es la receta operativa para convertir una investigación en documentación publicable. Se aplica tanto a un dominio nuevo como a una actualización de un caso existente. La [metodología documental](/method/explanations/documentation-methodology) explica por qué seguimos estos pasos; aquí se explica cómo ejecutarlos. ## 1. Entender el terreno antes de editar Empieza por el estado del repositorio y por sus instrucciones: ```bash git status --short rg --files src/pages rg -n '^docId:|^domain:|^diataxis:|^scope:|^audience:|^kind:|^status:' src/pages ``` Lee `AGENTS.md`, la documentación de referencia y el índice del dominio antes de crear una ruta. Identifica también: * `src/pages/`: páginas canónicas que se renderizan, y el único sitio donde se escribe un hecho; * `vocs.config.ts`: navegación, redirecciones y rutas estables; * `tools/generate-agent-index.py`: generador del catálogo para agentes; * `public/agent-index.json`: salida generada; no la edites manualmente; * assets, symlinks, configuración y scripts que deban conservarse. Si una tarea requiere cambiar un workflow, una API, permisos o infraestructura, sepárala de la tarea documental. La lectura puede ser de solo lectura; no hagas un hot change para obtener evidencia. ## 2. Crear un inventario de evidencia Antes de redactar, anota las afirmaciones que quieres publicar y su fuente. Una tabla temporal en tus notas es suficiente: | Afirmación | Fuente que manda | Alcance de la lectura | Estado | Siguiente paso | | --- | --- | --- | --- | --- | | Estado del workflow | Plataforma | Entorno y versión leídos | Verificado / por confirmar | Revalidar antes de cambiar | | Contrato de integración | Servicio y código | Endpoint o tool concreto | Verificado | Confirmar owner | | Resultado de negocio | Backend responsable | Entorno y operación | Por confirmar | Ejecutar prueba controlada | | Decisión | Registro aprobado | Fecha y responsables | Por confirmar | Obtener aprobación | Usa exactamente estos estados cuando aplique: * **Verificado:** comprobado contra la fuente que manda. * **Por confirmar:** procede de una nota, snapshot, conversación o lectura indirecta que todavía no se ha contrastado. * **No encontrado:** se buscó y no hay una respuesta verificable. Para datos que caducan, conserva fecha, entorno, versión o identificador de la consulta. La ausencia de acceso también es un resultado: no lo conviertas en una afirmación positiva. ### Orden práctico de consulta 1. fuente de autoridad del hecho; 2. código o contrato del servicio que lo implementa; 3. documentos de producto, UAT y decisiones aprobadas; 4. dashboard para conocer la observabilidad, no para sustituir el resultado; 5. Slack autorizado para contexto y decisiones, nunca como único respaldo de un estado productivo. En Slack, resume solo el mensaje o hilo necesario y conserva su contexto. No copies un canal completo, transcripts, enlaces privados, PII o credenciales a la documentación. ## 3. Elegir dominio, propietario e intención La estructura es dominio primero y tipo de página después: ```text src/pages/use-cases// ├── tutorials/ aprender un recorrido completo ├── how-to/ completar una tarea conocida ├── explanations/ entender contexto, diseño y decisiones └── reference/ consultar contratos e inventarios ``` Elige una sola página propietaria para cada hecho: | El lector quiere… | Crea o actualiza… | | --- | --- | | Aprender el recorrido completo | `tutorials/` | | Resolver una tarea concreta | `how-to/` | | Entender por qué funciona así | `explanations/` | | Consultar un contrato o inventario | `reference/` | No uses `public`, `internal` o `shared` para crear ramas paralelas. Son metadatos de audiencia, no controles de acceso. Si una página sirve a dos intenciones, elige una propietaria y enlázala desde la otra. Para un subdominio, como TeLeo dentro de Super App, conserva la relación jerárquica en la ruta y en la navegación: ```text src/pages/use-cases/super-app// ``` Si una página ya publicada cambia de ubicación, conserva su `docId`, añade una redirección histórica en `vocs.config.ts` y actualiza todos los índices y referencias que la descubren. ## 4. Añadir metadatos correctos Cada página renderizada necesita metadatos completos. Usa un bloque de este estilo y adapta los valores al contenido real: ```md --- description: "Explica el valor de esta página en una frase." docId: "docs.use-cases..." scope: "use-case" useCase: "" domain: "" diataxis: "explanation" audience: "shared" kind: "explanation" status: "canonical" keywords: ["término principal", "sistema", "resultado"] --- ``` Reglas de los campos: * `docId` es estable y único; no lo cambies por mejorar un título; * `domain` y `diataxis` (tipo de página) describen la ubicación conceptual, no solo la ruta; * `scope` expresa el ámbito de propiedad; * `audience` orienta la lectura, no protege la página; * `kind` describe la función concreta de la página; * `status` distingue `canonical`, `working`, `generated` y `skeleton`; * `keywords` debe incluir términos que un agente buscaría; * añade `reviewedAt` solo con una fecha real cuando el contenido sea temporal o generado. No uses fechas de ejemplo. El primer párrafo debe decir qué es el tema, para quién es y qué permite hacer o entender. Después desarrolla el flujo normal, excepciones, sistemas implicados, fuente de verdad, datos, permisos, retención y pendientes según corresponda. ## 5. Separar lo que se observó de lo que se propone Usa etiquetas explícitas y no mezcles estados: * **as-is:** observado o respaldado por el contrato actual; * **to-be:** diseño objetivo o propuesta aún no habilitada; * **pendiente:** dato o decisión que falta; * **live:** versión que atiende tráfico; * **latest:** versión más reciente conocida, que puede no estar publicada; * **snapshot:** lectura estructurada con alcance temporal. Una interfaz visible, un HTTP 200, un label o una tarjeta KPI no demuestra por sí solo que exista un resultado de negocio. Explica qué evidencia prueba cada capa y qué comprobación queda abierta. Mantén separadas estas responsabilidades: 1. producto y alcance para el cliente; 2. workflow y decisiones de enrutado; 3. contrato e integración de cada backend; 4. observabilidad y agregaciones del dashboard; 5. operación, UAT y rollback; 6. publicación, navegación e índice para agentes. ## 6. Redactar con seguridad y en el idioma del repositorio * Escribe y revisa el contenido en español antes de renderizarlo. * No publiques secretos, tokens, API keys, cookies, credenciales, PII, transcripts completos, exportaciones o rutas internas. * Redacta ejemplos con datos sintéticos y mínimos. * Define los acrónimos la primera vez y enlaza el [glosario](/reference/glossary). * Explica la fuente de verdad: el dashboard observa; el backend responsable confirma el resultado. * Si dos fuentes discrepan, conserva la discrepancia y asigna su resolución; no elijas una versión por intuición. * Usa diagramas solo para aclarar relaciones reales y valida que no presenten una propuesta como si fuera un flujo productivo. ## 7. Integrar la página en el sitio Cuando el contenido esté listo, revisa el conjunto, no solo el archivo nuevo: 1. índice del dominio y, si aplica, índice de la sección Diátaxis; 2. `vocs.config.ts` y barra lateral visible; 3. redirecciones si se movió o sustituyó una ruta; 4. enlaces desde dominios relacionados; 5. `src/pages/reference/source-map.md` si se incorpora una nueva clase de fuente; 6. metadatos y catálogo generado para agentes; 7. `README.md` o `AGENTS.md` solo si cambia la estructura o la política del repositorio. No dupliques una capacidad solo para que aparezca en dos menús. Enlaza a su propietario canónico. ## 8. Validar antes de publicar Ejecuta las comprobaciones del repositorio: ```bash npm run typecheck npm run agent-index npm run build git diff --check ``` `npm run build` limpia la salida, regenera el índice, localiza la interfaz de Vocs y conserva la salida SSR necesaria para MCP y las rutas dinámicas. Además, según el alcance: * comprueba que el JSON de `public/agent-index.json` sea válido y que no haya `docId` ni rutas duplicadas; * prueba la página de entrada, la búsqueda, los enlaces, las redirecciones y el cambio de tema en la salida publicada; * verifica que las tablas, diagramas Mermaid y títulos se rendericen; * prueba rutas nuevas y alias históricos con HTTP 200 o 307, respectivamente; * revisa `git diff --stat`, `git status --short` y los riesgos residuales. La [guía de validación de una publicación](/method/how-to/publish) contiene la lista de comprobación de salida. La [referencia de procedencia](/reference/source-map) define qué fuente manda para cada clase de hecho. ## 9. Publicar con separación de responsabilidades Haz un commit documental aislado, con un mensaje que describa el alcance. No mezcles en él cambios de workflow, infraestructura, credenciales o dashboard. Una publicación documental y una release de workflow son decisiones distintas: * documentar explica un comportamiento y sus límites; * publicar el sitio hace visible ese texto; * una release cambia el comportamiento que atiende tráfico y necesita su propio issue, pruebas, aprobación, ventana de observación y rollback. Antes de anunciar el cambio, indica qué se verificó, qué sigue por confirmar y qué fuentes no pudieron consultarse. Una documentación honesta incompleta es preferible a una documentación completa que convierta una hipótesis en una capacidad. ## Checklist rápida * \[ ] Leí las instrucciones y encontré la página propietaria. * \[ ] Registré fuente, alcance, fecha o versión de cada hecho temporal. * \[ ] Elegí dominio y tipo de página sin duplicar contenido. * \[ ] Añadí metadatos completos y keywords útiles. * \[ ] Separé verificado, por confirmar, no encontrado, as-is y to-be. * \[ ] No incluí secretos, PII, transcripts ni rutas internas. * \[ ] Actualicé índice, navegación, redirects y enlaces necesarios. * \[ ] Regeneré `public/agent-index.json` y ejecuté la validación. * \[ ] Dejé claro el alcance de publicación y los riesgos residuales.