Heathrow cerrado: Suspensión de vuelos debe continuar en los próximos días, afirma gerente del aeropuerto de Londres
Do site da BBC
British Airways estimó que 85% de sus vuelos programados se realizarían el sábado, pero con retrasos en todos los vuelos. A las 7:00 a.m. GMT, la mayoría de las salidas habían seguido como se esperaba, pero de las llegadas, nueve de las primeras 20 llegadas programadas fueron canceladas.
Nueva actualización para Minecraft añade templos submarinos
There has been an error in my update
api_key = "a quick brown fox"
fetch("https://api.example.com/data", headers: { 'Authorization' => api_key })
Por favor, ayúdame a corregirlo.
Documentación como código
Crear borradores con formato enriquecido y trabajar con la documentación de la misma manera que con el código. Esto proporciona varias ventajas:
- Ahorro de tiempo en formateo y conversión
- Generación automática de documentación online
- Modo offline (gracias a la caché del navegador), especialmente valioso:
- En redes cerradas del cliente
- En zonas sin internet.
“Los clientes han valorado mucho esta posibilidad” - me gustaría escribir, pero en Rusia somos escasos para dar feedback sobre cosas útiles. Para entender que el formato se ha adoptado, me basta con la valoración de un cliente que utilizó una página en caché durante un año e intentó comprender a los chicos del proyecto que mencionaban nuevos diagramas y texto que el cliente no había visto. Y cuando abrieron la página desde otro ordenador, entendieron que sin internet no se abría para nadie más. Por lo tanto, el tiempo dedicado a la documentación no fue en vano.
Objetivo: documentación como código
Crear borradores con formato enriquecido y trabajar con la documentación de la misma manera que con el código. Esto proporciona varias ventajas:
- Ahorro de tiempo en formateo y conversión
- Generación automática de documentación online
- Modo offline (gracias a la caché del navegador), especialmente valioso:
- En redes cerradas del cliente
- En zonas sin internet.
“Los clientes han valorado mucho esta posibilidad” - me gustaría escribir, pero en Rusia somos escasos para dar feedback sobre cosas útiles. Para entender que el formato se ha adoptado, me basta con la valoración de un cliente que utilizó una página en caché durante un año e intentó comprender a los chicos del proyecto que mencionaban nuevos diagramas y texto que el cliente no había visto. Y cuando abrieron la página desde otro ordenador, entendieron que sin internet no se abría para nadie más. Por lo tanto, el tiempo dedicado a la documentación no fue en vano.
Pila de tecnologías elegida
La base es el formato Markdown, porque:
- Es compatible con GitLab, YouTrack, algunos mensajeros
- Es reconocido correctamente por todos los LLM modernos
- Evita problemas con las versiones de Word, imágenes “perdidas” y formatos incompatibles.
A partir del borrador se puede obtener inmediatamente:
- Versión online
- PDF estricto y bonito con el mismo estilo que la versión online.
Práctica actual de documentación
Hoy en día, la documentación:
- Se escribe en formato Markdown
- Se almacena en GitLab:
- Accesible a todos los empleados según el modelo de roles
- Soporta edición multiusuario
- Se recopila automáticamente en versión online:
- Se utiliza un contenedor Docsify
- La actualización ocurre cada minuto
- Los sitios se publican en internet a través de DNS (con nombre de 3 o 4 niveles para cada proyecto)
- Se exporta a PDF con un estilo uniforme (basado en Vue.js), igual para el sitio y el archivo
- Los diagramas se crean en dos formatos:
- Draw.io (outline, para esquemas complejos)
- Mermaid (inline, directamente en Markdown)
- Exportación de diagramas:
- En SVG (formato principal)
- A veces en PNG (para plataformas incompatibles)
- Incluyendo el código fuente del diagrama dentro del archivo.
Modelo de tres niveles de documentación - y su simplificación
Inicialmente, consideré tres niveles de documentación:
- Borradores — personales, que cambian rápidamente notas.
- Documentación que cambia con frecuencia — materiales de trabajo colaborativos.
- Documentación estática — versiones finales y probadas.
Sin embargo, decidí:
- abandonar el anonimato y el aislamiento de los borradores,
- combinar el primer y segundo nivel en Wiki-borradores comunes basados en Discourse
- dejar la documentación estática en GitLab + Docsify.
Aunque no hay sincronización automática entre el segundo y tercer nivel, creo que este enfoque es viable: simplifica el flujo de conocimiento, reduce la barrera de entrada para los colegas y acelera la transición de una idea a la publicación.
Herramientas y formatos
||||
| — | — | — |
|Texto|Markdown (.md)|Formato de escritura principal|
|Almacenamiento|GitLab|Versionado, revisión, acceso por roles|
|Publicación online|Docsify (en contenedor Docker)|Construcción automática del sitio desde Git|
|Borradores y discusiones|Discourse|Elaboración colectiva de ideas|
|Diagramas (integrados)|Mermaid|Diagramas de bloques, secuencias directamente en Markdown|
|Diagramas (externos)|Draw.io (.drawio → .svg)|Esquemas arquitectónicos complejos|
|Exportación a PDF|Docsify + estilo Vue único|Para acceso offline y entrega al cliente|
\n
¿Qué más?
Hay más cosas en las que trabajar en el esquema:
- Sincronización entre Discourse y GitLab
- Refinamiento del proceso de revisión y transición a un estado listo para la publicación de la versión final
- Mantenimiento de la integridad de los enlaces
- Automatización de publicaciones
- Mecanismo de retroalimentación sobre las discrepancias encontradas y notificaciones sobre las correcciones.