Utiliza GIT para la documentación

A veces, no solo la documentación en sí, sino también el proceso de trabajo sobre ella puede ser crítico. Por ejemplo, en proyectos, gran parte del trabajo está relacionada precisamente con la preparación de la documentación, y un proceso incorrecto puede llevar a errores e incluso a la pérdida de información, lo que a su vez resulta en pérdida de tiempo y ganancias. Pero incluso si este tema no es central en tu trabajo y está en la periferia, un proceso adecuado puede mejorar la calidad del documento y ahorrarte tiempo.

El enfoque aquí presentado, con un ejemplo de implementación concreta, tiene un bajo umbral de entrada. Técnicamente, ya mañana puedes comenzar a trabajar de una manera diferente.

Planteamiento del problema

Necesitas crear algún documento o conjunto de documentos. Puede que sea documentación de proyecto o registro de tu red, o algo más simple, como describir procesos en tu empresa o en tu departamento. En general, se trata de cualquier documento o conjunto de documentos con texto, imágenes, tablas… Complicaremos la tarea en el sentido de que

1. este trabajo implica un esfuerzo colaborativo, el esfuerzo de un grupo o varios grupos de empleados
2. y al final quieres tener un documento en un formato específico, con atributos de estilo corporativo, creado según una plantilla determinada. Para ser precisos, consideraremos que es MS Word (.docx)

Hace 10 años, el enfoque habría sido claro: habríamos creado un documento en MS Word y de alguna manera organizado el trabajo de modificación.

Y ese enfoque sigue en vigor. También lo utilizan grandes integradores para crear documentación de proyecto. Pero intuitivamente se comprende que, si realmente trabajas intensivamente, con muchas modificaciones y discusiones, durante un período prolongado sobre un documento, este enfoque no es muy conveniente.

Ejemplo

Sentí agudamente este problema al trabajar en un gran integrador. El proceso de modificación de la documentación del proyecto era el siguiente:

1. el ingeniero descarga la última versión del documento de MS Word (.docx)
2. cambia el nombre
3. hace modificaciones en modo de seguimiento
4. envía el documento con las modificaciones 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 los cambios de datos en el archivo con la última versión, cambia la versión y lo publica en un recurso común
8. si hay comentarios, se inicia una discusión (por correo electrónico o reuniones)
9. se alcanza un consenso
10. a continuación, los puntos 3 a 9

Mientras el trabajo no era intenso, esto funcionaba más o menos. Pero en cierto momento, este proceso se convirtió en un cuello de botella para todo el proyecto y causó problemas. La cuestión es que todo se complica en cuanto los cambios se realizan con frecuencia y simultáneamente por varios equipos.

Así que, cuando pasamos a la etapa de prueba previa, comenzaron a aparecer varios problemas y, aunque menores, era necesario cambiar la documentación con frecuencia — cuatro equipos diferentes, diariamente, prácticamente al mismo tiempo, con discusiones. Todos estos cambios pasaban por un solo ingeniero — arquitecto. El archivo del diseño del proyecto era enorme y, como consecuencia, el arquitecto estaba abrumado con la rutina de trabajo, relacionada con una gran cantidad de copias y ediciones, cometía muchos errores, había que verificar todo nuevamente, re-enviar, y en general, se acercaba al caos.

En este caso, este enfoque, el enfoque de trabajo con el documento MS Word, funcionaba con gran dificultad y creaba problemas.

Git, Markdown

Enfrentado con el problema descrito en el ejemplo anterior, comencé a investigar este tema.
Vi que el uso de Markdown junto con Git está ganando popularidad en la creación de documentos.

Git es una herramienta para el desarrollo. Pero, ¿por qué no usarla para el proceso de documentación? En este caso, la cuestión del trabajo colaborativo queda resuelta. Pero para aprovechar al máximo las capacidades de Git, necesitamos un formato de documento de texto, debemos encontrar otra herramienta, no MS Word, y para estos fines, Markdown es ideal.

Markdown es un lenguaje de marcado de texto sencillo. Está diseñado para crear textos bien formateados en archivos de formato TXT. Si creamos nuestros documentos en Markdown, la combinación Markdown - Git parece natural.

Y todo estaría bien, y en este punto podríamos poner un punto final, si no fuera por nuestra segunda condición: "necesitamos un documento en un formato específico, con atributos de estilo corporativo, creado según una plantilla determinada" (y acordamos al principio que, para ser precisos, esto sería MS Word). Es decir, si decidimos usar Markdown, necesitamos de alguna manera convertir este archivo en el .docx requerido.

Existen programas de conversión entre diferentes formatos, por ejemplo, Pandoc.
Puede convertir un archivo Markdown al formato .docx con este programa.
Sin embargo, hay que entender que, en primer lugar, no todo lo que hay en Markdown se convertirá a MS Word y, en segundo lugar, MS Word es todo un país en comparación con la ordenada, pero aún así pequeña ciudad de Markdown. Hay una cantidad enorme de cosas que están en Word y no existen en ningún formato de Markdown. No se puede simplemente convertir su formato Markdown al deseado MS Word con ciertas claves de Pandoc. Por lo general, después de la conversión, es necesario "completar" el documento .docx obtenido manualmente, lo cual también puede ser costoso en términos de tiempo y llevar a errores.

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

Debido a que la funcionalidad de MS Word y Markdown no son equivalentes en general, creo que resolver esta tarea es imposible, pero ¿se puede hacer aplicable a situaciones concretas, a requisitos específicos? Mi experiencia ha demostrado que sí, se puede, y es probable que esto sea posible para muchas, o incluso la mayoría de las situaciones.

Solución de un problema específico

Así que, en mi caso, después de convertir el archivo usando Pandoc, tenía que hacer un procesamiento adicional de los archivos manualmente, es decir,

• agregar en Word campos con numeración automática de títulos (caption) de tablas e imágenes
• cambiar el estilo para las tablas

No encontré cómo hacer esto con herramientas estándar (Pandoc) o medios conocidos. Por lo tanto, apliqué un script de python con pywin32 paquete. Como resultado, obtuve una automatización completa. Ahora puedo convertir mi archivo Markdown a la forma requerida del documento MS Word con un solo comando.

Vea los detalles aquí.

Nota

En este ejemplo, por supuesto, estoy transformando un archivo Markdown abstracto, pero el mismo enfoque se aplicó a un documento 'real', y al final obtuve prácticamente el mismo documento de MS Word que antes obteníamos mediante formateo manual.

En general, con pywin32 obtenemos prácticamente un control total sobre el documento de MS Word, lo que permite modificarlo y darle el aspecto que exige su estándar corporativo. Por supuesto, se podría lograr esos mismos objetivos utilizando otras herramientas, como macros VBA, pero me resultaba más conveniente usar Python.

La fórmula breve de este enfoque es:

Markdown + Git -- (algo) --> MS Word

No es tan importante qué es 'algo'. En mi caso, fue Pandoc y Python con pywin32. Tal vez usted tenga otras preferencias, pero lo importante es que es posible. Y ese es el mensaje principal de este artículo.

En resumen, la idea es que con este enfoque trabaja únicamente con el archivo Markdown y utiliza Git para organizar la colaboración y el control de versiones, y solo cuando sea necesario (por ejemplo, para proporcionar documentación al cliente) crea automáticamente el archivo en el formato requerido (por ejemplo, MS Word).

El proceso

Creo que para muchos, la fórmula presentada arriba es suficiente para entender cómo se puede organizar el proceso de trabajo con la documentación. Pero de todos modos, generalmente me dirijo a ingenieros de redes, así que a grandes rasgos mostraré cómo puede verse ahora el proceso de trabajo y en qué se diferencia del enfoque de editar archivos de MS Word.

Para ser claros, elegiremos GitHub como plataforma para trabajar con Git. Entonces, debe crear un repositorio y colocar el archivo o archivos Markdown en la rama master con los que planea trabajar.

Consideraremos un proceso sencillo basado en 'github flow'. Su descripción se puede encontrar tanto en internet como en Habr.

Supongamos que cuatro personas están trabajando en la documentación y usted es una de ellas. Entonces se crean cuatro ramas adicionales, por ejemplo, con los nombres de estas personas. Cada uno trabaja localmente, en su rama y hace cambios con todos los comandos de git.

Al completar un bloque de trabajo, generas una pull request, iniciando así la discusión sobre tus cambios. Puede que durante la discusión, descubras que necesitas agregar o modificar algo más. En ese caso, realizas los cambios necesarios y creas una pull request adicional. Al final, tus cambios son aceptados y fusionados (merge) con la rama master (o rechazados).

Por supuesto, esta es una descripción bastante general. Sugiero que para crear un proceso detallado consultes a tus desarrolladores o busques personas con experiencia. Pero quiero señalar que la barrera de entrada a Git es bastante baja. Esto no significa que el protocolo sea simple, pero puedes empezar con algo básico. Si no sabes nada, creo que dedicando unas horas o tal vez días a estudiar e instalar, puedes comenzar a usarlo.

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

En realidad, los procesos son bastante similares, solo que has reemplazado

copiar archivo -> crear rama (branch)
copiar texto al archivo final -> fusión (merge)
copiar los últimos cambios a tu repositorio -> git pull/fetch
discusiones por mensaje -> pull requests
modo de seguimiento -> git diff
última versión aprobada -> rama master
copia de seguridad (copia en servidor remoto) -> git push
…

De este modo, has automatizado todo lo que ya tenías que hacer manualmente.

En un nivel más alto, esto te permite

• crear un proceso de cambios en la documentación que sea claro, simple y controlado.
• Ya que el documento final (en nuestro ejemplo MS Word) lo creas automáticamente, esto reduce la probabilidad de errores relacionados con el formato.

Nota

Por lo dicho anteriormente, creo que es evidente que, incluso si trabajas solo en la documentación, el uso de Git puede facilitar considerablemente tu trabajo.

Todo esto mejora la calidad de la documentación y reduce el tiempo de creación. Y un pequeño bono: aprenderás Git, lo que te ayudará en la automatización de tu red 🙂

¿Cómo pasar a un nuevo proceso?

Al comienzo del artículo mencioné que ya mañana puedes empezar a trabajar de manera diferente. ¿Cómo puedes trasladar tu trabajo a esta nueva dirección?

Aquí tienes una secuencia de pasos que probablemente tendrás que seguir:

• si tu documento es muy grande, divídelo en partes.
• convierte cada parte a Markdown (usando Pandoc, por ejemplo)
• instala uno de los editores de Markdown (yo uso Typora)
• probablemente tendrás que ajustar el formato de los documentos Markdown creados
• comienza a aplicar el proceso descrito en el capítulo anterior
• mientras tanto, comienza a modificar el script de conversión para tu tarea (o crea algo propio)

No es necesario esperar a que crees y depures perfectamente el mecanismo de conversión de Markdown a la apariencia requerida del documento. La cuestión es que, incluso si no puedes automatizar rápidamente el procedimiento de transformación de tus archivos Markdown, aún podrás hacerlo de alguna manera con Pandoc y luego llevarlo a su versión final manualmente. Por lo general, no necesitarás hacerlo con frecuencia, solo al final de ciertas etapas, y este trabajo manual, aunque incómodo, sigue siendo, a mi parecer, completamente aceptable en la etapa de depuración y no debería frenar demasiado el proceso.

Todo lo demás (Markdown, Git, Pandoc, Typora) ya está listo y no requiere esfuerzos ni tiempo especiales para empezar a trabajar con ellos.

Fuente: habr.com