Saltar al contenido
Engineer
Menú
Diseño
Español

Engineer / Portafolio

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.

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.

Contacto

¿Aún está definiendo lo que necesita?

Cuéntenos qué está fallando o qué intenta construir. Le diremos qué haría falta, cuánto costaría aproximadamente y si somos las personas adecuadas.

Desde 1.400 DKK por hora, sin IVA; y un precio por hora menor en una contratación más larga.

welcome@engineer.company +45 50 10 61 84 Copenhague, Dinamarca