# Analizador propio para la documentación

Sometí la documentación a un analizador propio — límite de líneas por archivo que solo puede reducirse, índice obligatorio y comprobación de rutas reales — que detectó seis de nueve planes marcados como terminados con tareas pendientes y catorce tareas obligatorias para commits que no figuraban en ningún documento.

agosto 2026

**Situación.** El repositorio se rige por instrucciones escritas: veintiséis documentos que cubren la política de calidad, el sistema de diseño, la accesibilidad, la impresión, los metadatos, la traducción y git. Las instrucciones siguen un patrón de deterioro concreto: crecen, se alejan del código, empiezan a remitir a archivos que se han movido y, a partir de cierto tamaño, dejan de leerse. Una regla que no se lee no es una regla.

**Tarea.** La documentación necesitaba el mismo tratamiento que el código: un analizador con límites que hicieran fallar la comprobación en lugar de aconsejar.

**Acción.** Ocho políticas, todas mecánicas. Un límite estricto de longitud del documento y otro más flexible que avisa. Un presupuesto de líneas por archivo que solo puede reducirse, de modo que un documento puede menguar y no volver a crecer. Un requisito de índice por encima de un umbral y un índice de secciones por encima de otro menor. Una regla de ubicación sobre qué documento es responsable de cada asunto. Validez de los enlaces. Honestidad de los planes: el estado que declara un plan debe coincidir con sus propias casillas. Una regla según la cual toda tarea que condiciona un commit debe mencionarse en algún documento. Y una comprobación de rutas reales, que verifica que cada ruta con directorio y cada símbolo de código que menciona un documento existe de verdad. La primera ejecución justificó todo el ejercicio: seis planes marcados como terminados con casillas pendientes, catorce tareas que condicionaban cada commit y no se mencionaban en ningún documento, tres enlaces rotos, un documento huérfano y tres rutas inexistentes en cinco documentos. Después, el presupuesto rechazó a su propia autora: escribir el resumen de este trabajo en el documento de desarrollo lo hizo superar su límite, y así nació un documento independiente, que es exactamente como se pretendía que funcionara la política.

**Resultado.** Veintiséis documentos que suman unas 2.666 líneas efectivas, cada uno con un presupuesto que no puede crecer, y con todas las rutas y los símbolos que mencionan comprobados contra el árbol de archivos. El hallazgo incómodo es el que merece repetirse: catorce comprobaciones condicionaban todos y cada uno de los commits sin aparecer en ningún documento, de modo que las reglas que imponía la máquina y las que leían las personas ya se habían separado.

---

- Función: Responsable técnica de producto
- Categorías: [Automatización y CI/CD](https://advisory.engineer.company/es/categories/automation/), [Pruebas y control de calidad](https://advisory.engineer.company/es/categories/testing/), [Python](https://advisory.engineer.company/es/categories/python/), [Dirección técnica](https://advisory.engineer.company/es/categories/technical-leadership/), [Gestión de proyectos](https://advisory.engineer.company/es/categories/project-management/), [Documentación](https://advisory.engineer.company/es/categories/documentation/)
- Servicios: [Dirección técnica y consultoría](https://advisory.engineer.company/es/services/technical-leadership/), [Gestión ágil de proyectos](https://advisory.engineer.company/es/services/project-management/), [Documentación técnica](https://advisory.engineer.company/es/services/technical-documentation/)

<https://engineer.company/es/portfolio/put-the-documentation-under-its-own-linter/>
