Por qué Git es una gran herramienta de gestión de documentación

A veces, no solo la documentación sino también el proceso de trabajo en ella puede ser crítico. Por ejemplo, en el caso de los proyectos, la mayor parte del trabajo está relacionado con la preparación de la documentación, y un proceso incorrecto puede generar errores e incluso pérdida de información y, en consecuencia, pérdida de tiempo y beneficios. Pero incluso si este tema no es fundamental para su trabajo, el proceso correcto aún puede mejorar la calidad del documento y ahorrarle tiempo.

El enfoque descrito aquí tiene un umbral de entrada bajo. Técnicamente, mañana puedes empezar a trabajar de una forma nueva.

Definición de tareas

Necesita crear un documento o un conjunto de documentos. Tal vez esta sea la documentación del proyecto o el registro de su red, o algo más simple. Por ejemplo, debe describir los procesos dentro de la empresa o su departamento. En general, estamos hablando de cualquier documento o conjunto de documentos que contengan texto, figuras, tablas… Compliquemos la tarea por el hecho de que:

1. Esto implica el trabajo conjunto, así como el esfuerzo de un grupo o varios grupos de empleados.
2. Como resultado, desea tener un documento en un formato determinado, con atributos de estilo corporativo y creado de acuerdo con una plantilla determinada. Para ser específicos, considerémoslo como MS Word (.docx)

Hace 10 años, el enfoque habría sido bastante inequívoco: habríamos creado un documento o documentos de MS Word y de alguna manera habríamos organizado la edición.

Este enfoque sigue siendo válido. Incluso lo utilizan grandes integradores al crear la documentación del proyecto. Sin embargo, es intuitivamente claro que si su trabajo en un documento es a largo plazo, intensivo e incluye muchas ediciones y debates, este enfoque no es muy conveniente.

Ejemplo

Estaba muy consciente de este problema mientras trabajaba para un gran integrador. El proceso de cambio de la documentación del proyecto fue el siguiente:

1. El ingeniero descarga la última versión de un documento de MS Word (.docx)
2. cambia su nombre
3. Realiza ediciones en modo pista
4. Envía el documento con ediciones al arquitecto.
5. También envía una lista de todas las correcciones con comentarios.
6. El arquitecto analiza los cambios.
7. Si todo está bien, copia estos cambios en el archivo de la última versión, cambia la versión y la sube a un recurso compartido.
8. Si hay algún comentario, se inicia una discusión (correo electrónico o reuniones)
9. Se llega a un consenso
10. Ir a los párrafos 3–9

Hasta que el trabajo fue intenso, de alguna manera funcionó. Pero en algún momento, este proceso se convirtió en el cuello de botella de todo el proyecto, lo que generó problemas. El punto es que las cosas empeoran tan pronto como varios equipos realizan cambios de manera frecuente y simultánea.

Cuando pasamos a la etapa de prueba preliminar, comenzaron a aparecer diferentes problemas. Aunque eran menores, teníamos que cambiar la documentación con frecuencia: cuatro equipos diferentes, todos los días, casi simultáneamente, con discusiones. Todos estos cambios pasaron por un ingeniero: el arquitecto. El archivo de diseño del proyecto era enorme y, como resultado, el arquitecto se vio abrumado por el trabajo rutinario que implicaba muchas copias y ediciones. Cometió muchos errores, todo tuvo que ser revisado y reenviado. En general, nuestro trabajo estuvo cerca del caos.

Entonces, este enfoque, el enfoque de trabajar en un documento de MS Word, funcionó con gran dificultad y creó problemas.

Git, descuento

Ante el problema descrito en el ejemplo anterior, comencé a investigar este tema.

Me di cuenta de que se estaba volviendo cada vez más popular usar Markdown junto con Git al crear documentos.

Git es una herramienta de desarrollo. Pero, ¿por qué no usarlo para el proceso de documentación? En este caso, el problema del trabajo multiusuario se resuelve. Pero para aprovechar al máximo el poder de Git, necesitamos un formato de documento basado en texto. Necesitamos encontrar otra herramienta, no MS Word. Y Markdown sería genial para esto.

Markdown es un lenguaje de marcado simple. Se utiliza para crear textos bellamente diseñados en archivos TXT normales. Si creamos nuestros documentos en Markdown, usar Git se verá bastante natural.

Y eso estaría bien si no fuera por nuestra segunda condición: “como resultado, desea tener un documento en un determinado formato, con atributos de estilo corporativo y creado de acuerdo con una determinada plantilla” (y acordamos al principio que sería MS Word). Entonces, si decidimos usar Markdown, debemos convertir este archivo de alguna manera al formato .docx requerido.

Hay programas para convertir entre diferentes formatos, por ejemplo, Pandoc . Con este programa, puede convertir un archivo Markdown a un formato .docx. Pero aún así, debe comprender que, en primer lugar, no todo lo que tiene Markdown se convertirá a MS Word y, en segundo lugar, MS Word es un país completo en comparación con la pequeña ciudad de Markdown. Hay una gran cantidad de cosas que Word tiene y Markdown no. No puede simplemente tomar ciertas claves Pandoc y convertir su formato Markdown en la forma deseada de MS Word. Por lo tanto, generalmente, después de la conversión, debe "refinar" el documento .docx resultante manualmente, lo que también puede llevar mucho tiempo y generar errores.

Si pudiéramos escribir un script que "completara" automáticamente lo que Pandoc no puede manejar, esa sería la solución perfecta.

Dado que MS Word y Markdown difieren esencialmente, creo que es imposible resolver este problema en general. Pero, ¿es posible hacerlo en situaciones específicas, requisitos específicos? Mi experiencia ha demostrado que sí, es posible, y muy probablemente posible en muchas o incluso en la mayoría de las situaciones.

Resolver un problema en particular

Entonces, en mi caso, después de convertir los archivos en Pandoc, tuve que procesar adicionalmente estos archivos manualmente, es decir

• Agregue campos de Word con la numeración automática de leyendas para figuras y tablas
• Cambiar estilos de tabla

No pude encontrar cómo hacer esto usando ningún medio estándar (Pandoc) o conocido. Entonces, apliqué un script de python con el paquete pywin32 . Como resultado, obtuve una automatización completa. Podría convertir mi archivo Markdown al formulario de MS Word deseado con solo un comando.

El pywin32 le permite obtener un control casi completo sobre los documentos de MS Word, lo que le permite cambiarlos y llevarlos a la forma que requiere su estándar corporativo. Por supuesto, se podrían lograr los mismos objetivos usando otras herramientas, por ejemplo, macros de VBA, pero me resultó más conveniente usar python.

Una fórmula corta para este enfoque:

 Markdown + Git - (something) → MS Word

No importa qué sea "algo". En mi caso, eso fue Pandoc y python con pywin32. Puede que tengas diferentes preferencias, pero lo importante es que es posible. Y ese es el mensaje principal de este artículo.

En resumen, la idea es que este enfoque le permita trabajar solo con archivos Markdown y usar Git para colaboración y control de versiones. Si es necesario (por ejemplo, para proporcionar documentación al cliente), crea automáticamente un archivo del formato deseado (por ejemplo, MS Word).

Proceso

Creo que para muchos de ustedes la fórmula anterior es suficiente para comprender cómo se puede organizar ahora el proceso de trabajar con documentación. Pero aun así, suelo centrarme en los ingenieros de redes. Entonces, le mostraré en términos generales cómo se vería el proceso de trabajo y en qué se diferencia de la edición de archivos de MS Word.

Para ser específicos, elijamos GitHub como la plataforma para trabajar con Git. Luego, debe crear un repositorio y agregar el archivo o archivos Markdown con los que planea trabajar a la rama principal.

Suponga que cuatro personas están trabajando en la documentación y usted es una de ellas. Luego, se crean cuatro sucursales adicionales, por ejemplo, con los nombres de estas personas. Cada persona trabaja localmente, en su propia rama, y realiza cambios utilizando todos los comandos necesarios de git.

Después de completar un trabajo por separado, crea una solicitud de extracción, iniciando así una discusión sobre sus cambios. Quizás durante la discusión, resulta que necesita agregar o cambiar algo más. En este caso, realiza los cambios necesarios y crea una solicitud de extracción adicional. Eventualmente, sus cambios se confirman y se fusionan con la rama principal (o se rechazan).

Por supuesto, esta es una descripción bastante general. Sugiero contactar a sus desarrolladores o buscar personas con experiencia para crear un proceso detallado. Pero me gustaría señalar que Git tiene un umbral de entrada bastante bajo. Esto no significa que el protocolo sea simple, pero puede comenzar de manera simple. Si no sabe nada, creo que después de pasar unas horas o quizás días aprendiendo e instalando, puede comenzar a usarlo.

¿Cuál es el uso de este enfoque en comparación con, por ejemplo, el proceso descrito en el ejemplo anterior?

Los procesos son bastante similares, simplemente reemplaza:

• Copiar un archivo → crear una rama
• Copiar texto a un archivo de destino → fusionar
• Copie los últimos cambios en usted mismo → git pull/fetch
• Discusión de chat → solicitudes de extracción
• Modo de seguimiento → git diff
• Última versión aprobada → rama principal
• Copia de seguridad (copiar a un servidor remoto) → git push

Así, automatizas todo lo que tienes que hacer manualmente.

A un nivel superior, te permite:

• Cree un proceso de cambio de documentos claro, simple y controlable
• Dado que crea el documento final (en nuestro caso, MS Word) automáticamente, esto reduce el riesgo de errores asociados con el formato

En vista de lo anterior, creo que es obvio que aunque seas el único que trabaja con documentación, usar Git puede facilitar mucho tu trabajo.

¿Cómo empiezo un nuevo proceso?

Al comienzo del artículo, escribí que mañana puedes comenzar a trabajar de una manera nueva. Entonces, ¿cómo llevar tu trabajo en una nueva dirección?

Esta es la secuencia de pasos que probablemente necesitará seguir:

• Si su documento es demasiado grande, divídalo en partes
• Convierta cada parte a Markdown (usando Pandoc, por ejemplo)
• Instale uno de los editores de Markdown (yo uso Typora)
• Lo más probable es que necesite corregir los documentos con formato Markdown creados
• Comience a seguir el proceso descrito en el capítulo anterior.
• Comience a modificar el script de conversión para su tarea (o cree algo propio)

No tiene que esperar hasta que cree y ajuste el motor de conversión Markdown → el tipo de documento requerido. El hecho es que incluso si no puede automatizar rápidamente el proceso de conversión de sus archivos Markdown, aún puede usar Pandoc para convertirlos a algún formato y luego llevar manualmente sus archivos al formato que necesita. Por lo general, no necesita hacer esto con demasiada frecuencia, sino solo al final de ciertas etapas. Aunque este trabajo manual es un inconveniente, sigue siendo, en mi opinión, bastante aceptable en la etapa de depuración y no ralentizará mucho el proceso.

Todo lo demás (Markdown, Git, Pandoc, Typora) está listo y no requiere mucho esfuerzo ni tiempo para comenzar.