## Documentos y documentación
<div data-theme-toc="true"></div>
`Nueva carpeta(2)/` `Nuevo documento de texto.txt` `Nuevo documento de texto(2).txt`
\- ¿Dónde lo guardé...?
# Supuestos difíciles
Nació en el ajetreo de la ejecución de tareas la idea de optimizar la escritura de documentos. Los frecuentes cambios entre pipelines, monitoreo, automatización, RnD, soporte y un detallado seguimiento del tiempo no permitían concentrarse en la documentación.
# Registrar la historia
Necesitaba registrar mis acciones, complementar los textos con imágenes, enlaces y marcas de tiempo, sin permitir cruces de temas en el mismo borrador. Tenía que hacerlo para poder recordar fácilmente la secuencia de trabajo más tarde.
\- Varias veces el registro de Putty/Bash ayudó a restaurar una secuencia confusa de trabajo en producción. No ignores esta posibilidad.
# Publicación
En el futuro, quería convertir el borrador en un documento de trabajo y publicarlo como parte de la documentación del proyecto. En última instancia, se logró salir más allá de los límites.
El objetivo era crear borradores con formato extendido y trabajar con la documentación como si fuera código.
Esto permitió ahorrar tiempo en el formateo y la conversión a un formato publicado estándar.
# Formato en línea
En última instancia, el formato Markdown+Git permitió generar automáticamente documentación en línea. Como beneficio adicional, se obtuvo un modo sin conexión accesible desde la caché del navegador. En redes privadas para clientes, en un avión y donde no haya Internet, este modo fue muy útil. A los clientes también les gustó.
Markdown se utiliza en Gitlab, YouTrack, algunos mensajeros y es reconocido por todos los modelos de LLM.
# Borradores compartidos
\- Si tu trabajo no está relacionado con las finanzas, tus borradores no deben estar ocultos. Al contrario, permite que otros trabajen con ellos.
Mi deseo de hacer que los borradores sean públicos impulsó la creación de “documentación como código”. El equipo de DevOps se liberó de archivos de texto anónimos y problemas de búsqueda de "¿dónde lo guardé?". No hay problemas con diferentes versiones de Word, imágenes rotas y similares. Además, desde el borrador se genera automáticamente una versión en línea y un PDF elegante y estricto.
# Documentación hoy
- Se escribe en formato Markdown (editor Typora o similar con guardado automático + commits en IDEA/PyCharm)
- Se almacena en Gitlab (accesible para todos los empleados según el modelo de roles, admite la edición multiusuario)
- Se genera automáticamente una versión en línea en un contenedor Docsify (la actualización del código ocurre cada minuto); los sitios se conectan a Internet mediante DNS
- Se puede exportar fácilmente a PDF con el mismo formato que un sitio web utilizando Vue.js tanto para el archivo como para el sitio
- Los diagramas se crean en formato Drawio (outline) y Mermaid (inline)
- Los diagramas se exportan a svg (y ocasionalmente a png para plataformas no compatibles) e incluyen el código fuente integrado
# Qué falta
Para la mayoría de los usuarios, no les interesa un lugar único donde se almacena la documentación y que puedan editarla en modo multiusuario. Hay unos pocos editores-colaboradores, mientras que hay muchos usuarios simples. Para ellos es importante encontrar rápidamente el documento en la versión más reciente, compartirlo fácilmente. Por lo tanto, ¿cómo?:
1. Crear una lista automática de documentos.
2. Clasificar los enlaces en el texto según la relevancia de los documentos (no en función de la frecuencia de las actualizaciones recientes, sino del contenido - nadie quiere un documento que aparezca en la parte superior de la lista solo por correcciones cosméticas).
3. Permitir realizar pequeñas modificaciones directamente en el documento sin tener que trabajar con el código fuente.
4. Actualizar la documentación "en lote" cuando algunas partes de la documentación están interconectadas y se reutilizan parcialmente o totalmente.
5. Generar automáticamente la documentación, ya que rápidamente se vuelve obsoleta.
6. Asegurarse de que la documentación sea coherente no solo con el contenido en sí, sino también de recordar a los empleados que corrijan o complementen las réplicas públicas en los canales o comunidades correspondientes. Las réplicas de personas con relación a la documentación son primordiales, más que la documentación misma - este es un hecho establecido.