Saltar al contenido

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.

documentación bajo su propio analizador

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.

  • Mano con un bolígrafo sobre un portapapeles
    Foto: Mohamed_hassan / Pixabay
  • Documentos, papeles, archivos
    Foto: Tomasz_Mikolajczyk / Pixabay

Aplique esta experiencia a su proyecto

Utilice «Analizador propio para la documentación» como punto de partida para un reto similar en su organización. Los servicios que respaldan este trabajo están disponibles para su proyecto. Alguien de su lado de la mesa cuando una decisión sobre proveedores, presupuesto o arquitectura necesita una segunda opinión informada.

Explore nuestros servicios Póngase en contacto

Mire más allá del resultado

Lea la situación, las decisiones y el resultado de este ejemplo. Podemos hablar de qué partes se adaptan a sus restricciones y cuáles necesitan otro enfoque. Analizador propio para la documentación — documentación bajo su propio analizador

Explore nuestros servicios Póngase en contacto

Una parte de una trayectoria más amplia — y toda ella está en este sitio.

Cada entrada sigue la misma estructura: la situación, la tarea, lo que hicimos y lo que cambió.

Vea la trayectoria completa

Defina la mejora que necesita

Describa la decisión, las personas afectadas y las opciones ya consideradas. Podemos hacer explícitos los compromisos entre objetivos y dejar una recomendación documentada.

Vea cuánto cuesta Póngase en contacto

¿Está quedándose desactualizada su documentación sin que lo advierta?

Pregunte por las decisiones detrás de «Analizador propio para la documentación». Hablará con las personas que pueden explicar el trabajo y valorar su propio proyecto.

Explore nuestros servicios
welcome@engineer.company +45 50 10 61 84 Copenhague, Dinamarca
Código QR de 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.
Llévese esta páginahttps://advisory.engineer.company/es/portfolio/put-the-documentation-under-its-own-linter/