Heathrow fechado: Suspensão de voos deve continuar nos próximos dias, afirma gerente do aeroporto de Londres
[detalhes=Do site da BBC]
A British Airways estimou que 85% dos seus voos programados seriam realizados no sábado, mas com atrasos em todos os voos. Às 7h GMT, a maioria das partidas havia ocorrido conforme o esperado, mas, das chegadas, nove dos primeiros 20 voos programados para pousar foram cancelados.
[/details]
Problema: documentación en el entorno de multitarea
La confusión al realizar tareas cotidianas y los frecuentes saltos hacia “incendios” no dejaban tiempo para la documentación. El problema de optimizar su escritura se había planteado entre tantos saltos:
- CI/CD-pipelines
- monitoreo
- automatización
- R&D
- soporte a lo anterior
- soporte al cliente
- y contabilidad detallada del tiempo
No había posibilidades de enfocarse en la documentación de calidad. Y, por supuesto, no sé hacerlas “a medias”.
Lo que se requería:
- registrar las acciones
- ampliar los registros con imágenes, enlaces etiquetas y fechas
cenasaevitar mezclar distintos temas en un solo borrador - permitir iniciar el trabajo en una computadora y continuarlo en otra, incluidos dispositivos móviles
- guardar los borradores de forma automática para que estuvieran disponibles desde cualquier dispositivo
- recuperar fácilmente el hilo del trabajo en el futuro
- compartir borradores a lo largo del proceso.
En un principio la idea era convertir un borrador en un documento completo y publicarlo como parte de la documentación proyectal sin ataduras a los hitos del cronograma. En el final encontré una aproximación que permitió ampliar su uso más allá del uso local y se convirtió en una de facto parte de la infraestructura general de conocimiento, siendo usada frecuentemente como estándar en los proyectos.
En el final construí un sistema de documentación flexible, escalable y orientado a las personas que toma en consideración las realidades del trabajo de ingeniero bajo alta carga. Desde la exclusión de los borradores aislados hacia discusiones abiertas — una decisión importante— no solo acelera la consolidación del documento sino también impulsa a la equipo al proceso.
Objetivo: documentación como código
Crea borradores con formatos ampliados y trabaja con la documentación como si fuera código de software. Esto brinda varias ventajas:
- Ahorro de tiempo en el formatoación y conversión
- generación automática de documentación online
- disponibilidad del modo offline (gracias al caché del navegador), lo cual resulta especialmente valioso:
- en redes cerradas del cliente
- en zonas sin internet.
“Los clientes valoran esta capacidad” — quería escribir yo, pero en Rusia raramente se mencionan cosas útiles. Para saber que el formato se ha asentado me basta con la valoración de un cliente que un año utilizó la página cachée y intentó comprender a los chicos del proyecto que citaban nuevas esqueletos y texto, que el cliente no había visto. Y cuando abrieron la página en otro computador, descubrieron que sin internet no se podía acceder a ella en ningún dispositivo excepto su propio. Pues bien, eso significa que el tiempo dedicado a la documentación fue invertido con éxito.
Tecnologías elegidas
t
La base está formada por formato Markdown porque:
- es soportado en GitLab, YouTrack, algunos mensajeros
- se reconoce correctamente todas las LLM modernas
- permite evitar problemas de versiones del Word, imágenes “arrugadas” y formatos incompatibles.
Desde el borrador se puede obtener:
- una versión online
- un PDF riguroso y con estilo tan bonito como la versión web (a partir de Vue.js)
Practica documental actual
documentación hoy en día:
- se escribe en formato Markdown
- se almacena en GitLab:
- accesible a todos los empleados bajo el modelo de roles
- soporta la edición multipersonas
- se reconstruye automáticamente en versión online:
- utiliza Docsify
- se actualiza cada minuto
- las webs se publican en internet mediante DNS (con nombre de nivel 3 o 4 para cada proyecto)
- se exporta a PDF con un estilo único (basado en Vue.js), igual al del sitio web
- las diagramas se crean en dos formatos:
- Draw. io (formato “bocadillo”, para esquemas complejos)
- Mermaid (inline, directamente dentro de Markdown)
- exportar diagramas:
- SVG (formato principal)
- a veces PNG (para plataformas incompatibles)
- con la inclusión del código fuente de la propia gráfica.
Modelo de tres niveles de documentación — y su simplificación
En un principio consideraba tres niveles:
- Borradores personales — notas rápidas y cambiantes.
- Documentación que se modifica con frecuencia— materiales de trabajo colaborativos.
- Documentación estática — versiones finales, verificadas.
Sin embargo decidí:
- rechazar la anonimato y aislamiento de los borradores,
- unir el primer y segundo niveles en un Wiki común basado en Discourse
- conservar la documentación estática en GitLab + Docsify.
Aunque entre el segundo y el tercer niveles no hay sincronización automática, considero esta estrategia viable: simplifica la fluidez del conocimiento, baja el umbral de entrada para los colegas y acelera la transición de idea a publicación.
Herramientas y formatos
|—|—|—|
|Texto|Markdown (.md)|Formato principal de escritura|
|Almacenamiento|GitLab|Versión, revisión, acceso por roles|
|Página web en línea|Docsify (en contenedor Docker)|Recolección automática del sitio a partir de Git|
|Borradores y debates|Discourse|Procesos colectivos de ideas|
|Diagramas integrados|Mermaid|Sinuosidades, secuencias directamente en Markdown|
|Diagramas externos|Draw. io (.drawio → .svg)|Esquemas arquitectónicos complejos|
|Exportación a PDF|Docsify + estilo único de Vue.js|Pérdida offline y transferencia a clientes|
Lo demás
En la cartera todavía hay que trabajar en:
- sincronización entre Discourse y Gitlab
- pulir el proceso de revisión y traducción al estado listo para publicación final
- mantener la integridad de los enlaces
- automatizar las publicaciones
- mecanismo de retroalimentación por desacuerdos y notificaciones de correcciones.