A veces, no solo la documentación en sí, sino también el proceso de trabajar en ella pueden ser críticos. 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 provocar errores e incluso la pérdida de información y, en consecuencia, la pérdida de tiempo y ganancias. Pero incluso si este tema no es central para su trabajo y se encuentra en la periferia, el proceso correcto puede mejorar la calidad del documento y ahorrarle tiempo.
El enfoque descrito aquí, con
un ejemplo de una implementación específica , tiene un umbral de entrada bajo. Técnicamente, mañana puedes comenzar a trabajar de una manera nueva.
Declaración del problema.
Necesita crear un determinado documento o un conjunto de documentos. Quizás esta sea la documentación del proyecto o el registro de su red, o algo más simple, por ejemplo, debe describir los procesos en la empresa o en su departamento. En general, estamos hablando de cualquier documento o conjunto de documentos con texto, imágenes, placas ... Complicamos la tarea por el hecho de que
- este trabajo implica trabajo conjunto, los esfuerzos de un grupo o varios grupos de empleados
- En la salida, desea tener un documento en un formato específico, con atributos de estilo corporativo, creado de acuerdo con una plantilla específica. Para mayor precisión, asumiremos que esto es MS Word (.docx)
Hace 10 años, el enfoque sería inequívoco: creamos un documento o documentos de MS Word y de alguna manera organizamos el trabajo sobre el cambio.
Y este enfoque sigue siendo válido. También lo utilizan los grandes integradores al crear la documentación del proyecto. Pero es intuitivamente claro que si usted es realmente intensivo, con muchas ediciones y discusiones, durante mucho tiempo trabajando en un documento, este enfoque no es muy conveniente.
Ejemplo
Sentí bastante este problema mientras trabajaba en un gran integrador. El proceso de cambiar la documentación del diseño fue el siguiente:
- el ingeniero descarga la última versión del documento de MS Word (.docx)
- cambia el nombre
- realiza cambios en el mod de pista
- envía el documento con correcciones al arquitecto
- también envía una lista de todas las correcciones con comentarios
- el arquitecto analiza el cambio
- si todo está bien, copia los datos de cambio en el archivo con la última versión, cambia la versión y lo coloca en un recurso compartido
- Si hay comentarios, se inicia una discusión (correo electrónico o reuniones)
- se alcanza el consenso
- otros párrafos 3 a 9
Si bien el trabajo no fue intenso, de alguna manera, pero aún así funcionó. Pero en cierto punto, este proceso se convirtió en el cuello de botella de todo el proyecto y condujo a problemas. El hecho es que todo se vuelve malo tan pronto como varios equipos realizan cambios frecuentes y simultáneos.
Entonces, cuando pasamos a la etapa de prueba preliminar, comenzaron a aparecer varios problemas y, aunque en los detalles, tuvimos que cambiar la documentación a menudo: cuatro equipos diferentes, diariamente, casi simultáneamente, con discusiones. Todos estos cambios pasaron por un ingeniero: un arquitecto. El archivo con el diseño del proyecto fue enorme y, como resultado, el arquitecto se vio abrumado por el trabajo de rutina asociado con muchas copias, ediciones, cometió muchos errores, tuve que verificar dos veces, volver a enviar y, en general, estaba cerca del caos.
En este caso, este enfoque, el enfoque de trabajar en un documento de MS Word, funcionó con gran chirrido y creó problemas.
Git Markdown
Ante el problema descrito en el ejemplo anterior, comencé a investigar este problema.
Vi que usar
Markdown con
Git al crear documentos se está volviendo cada vez más popular.
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 queda resuelto. Pero para hacer un uso completo de las características de Git, necesitamos un formato de texto para el documento, necesitamos encontrar otra herramienta, no MS Word, y Markdown es excelente para estos propósitos.
Markdown es un lenguaje de marcado de texto simple. Está diseñado para crear textos bellamente diseñados en archivos TXT normales. Si creamos nuestros documentos en Markdown, entonces el enlace Markdown-Git parece natural.
Y todo estaría bien, y en este lugar sería posible poner fin si no fuera por nuestra segunda condición: "en la salida necesitamos un documento en un formato determinado, con atributos de estilo corporativo creados de acuerdo con una plantilla determinada" (y primero acordamos que para certeza, será MS Word). Es decir, si decidimos usar Markdown, entonces debemos convertir de alguna manera este archivo a .docx del tipo requerido.
Hay programas para convertir entre diferentes formatos, por ejemplo,
Pandoc .
Puede convertir el archivo Markdown a formato .docx con este programa.
Pero aún así, debe comprender que, en primer lugar, no todo lo que está en Markdown se convertirá a MS Word y, en segundo lugar, MS Word es un país entero en comparación con el delgado, pero aún pequeño pueblo, Markdown. Hay una gran cantidad de todo lo que está en Word y en ninguna forma está en Markdown. No puede simplemente llevar su formato Markdown con las teclas Pandoc deseadas a la forma deseada de MS Word. Por lo general, después de la conversión, debe "refinar" el documento .docx recibido manualmente, lo que nuevamente puede llevar mucho tiempo y generar errores.
Si pudiéramos escribir un script que automáticamente "terminara" lo que Pandoc no podría hacer, sería una solución ideal.
Debido al hecho de que la funcionalidad de MS Word y Markdown no es idéntica en términos generales, creo que es imposible resolver este problema, pero ¿se puede hacer en relación con situaciones específicas, requisitos específicos? Mi experiencia ha demostrado que sí, es posible y lo más probable es que sea posible para muchas, o incluso para la mayoría de las situaciones.
Solución de un problema particular.
Entonces, en mi caso, después de convertir el archivo usando Pandoc, tuve que hacer manualmente el procesamiento de archivos adicionales, a saber
- agregar campos en Word con numeración automática de subtítulos de tablas e imágenes
- cambiar el estilo de las mesas
No encontré cómo hacer esto usando estándar (Pandoc) o medios conocidos. Por lo tanto, apliqué un script de python con el paquete
pywin32 . Como resultado, obtuve la automatización completa. Ahora puedo convertir mi archivo Markdown a la forma deseada del documento de MS Word con un comando.
Ver detalles
aquí .
Observación
En este ejemplo, yo, por supuesto, convertiré un archivo de Markdown abstracto, pero se aplicó exactamente el mismo enfoque al documento de "combate", y en la salida recibí casi exactamente el mismo documento de MS Word, que habíamos recibido previamente por formateo manual.
En general, con pywin32 obtenemos un control casi completo sobre el documento de MS Word, lo que nos permite cambiarlo y llevarlo al aspecto que requiere su estándar corporativo. Por supuesto, estos mismos objetivos podrían lograrse utilizando otras herramientas, por ejemplo, macros VBA, pero fue más conveniente para mí usar python.
Una breve fórmula para este enfoque:
Markdown + Git -- () --> MS Word
No es tan importante lo que es "algo". En mi caso, fue Pandoc y python con pywin32. Es posible que tenga diferentes preferencias, pero lo importante es que esto es posible. Y este es el mensaje principal de este artículo.
En resumen, la idea es que con este enfoque solo trabaje con el archivo Markdown y use Git para organizar la colaboración y el control de versiones, y solo si es necesario (por ejemplo, para proporcionar documentación al cliente) cree automáticamente el archivo del formato deseado (por ejemplo, MS Word )
El proceso
Creo que para muchos la fórmula dada anteriormente es suficiente para entender cómo se puede organizar ahora el proceso de trabajar con la documentación. Sin embargo, por lo general, me concentro en los ingenieros de redes, por lo que explicaré en general cómo puede verse ahora el proceso y cómo difiere del enfoque para editar archivos de MS Word.
Para mayor claridad, elegiremos GitHub como la plataforma para trabajar con Git. Luego debe crear un repositorio y colocar el archivo Markdown o los archivos con los que planea trabajar en la rama maestra.
Veremos un proceso simple basado en el flujo de github. Su descripción se puede encontrar tanto en Internet como en el
Habr .
Suponga que cuatro personas están trabajando en la documentación y usted es uno de ellos. Luego se crean cuatro ramas adicionales, por ejemplo, con los nombres de estas personas. Cada uno trabaja localmente, en su propia rama y realiza cambios con todos los
comandos git necesarios.
Después de completar un trabajo terminado, usted forma una solicitud de extracción, iniciando así una discusión de sus cambios. Quizás en el proceso de discusión, resulta que debería agregar o cambiar algo más. En este caso, realiza los cambios necesarios y crea una solicitud de extracción adicional. Al final, sus cambios son aceptados y fusionados con la rama maestra (o rechazada).
Por supuesto, esta es una descripción bastante general. Sugiero contactar a sus desarrolladores o encontrar personas con conocimientos para crear un proceso detallado. Pero quiero señalar que el umbral para ingresar a Git es bastante bajo. Esto no significa que el protocolo sea simple, pero puede comenzar con uno simple. Si no sabe nada en absoluto, creo que, después de haber pasado varias horas o quizás días para estudiar e instalar, puede comenzar a usarlo.
¿Cuál es el uso de este enfoque en comparación, por ejemplo, con el proceso descrito en el ejemplo anterior?
De hecho, los procesos son bastante similares, acabas de reemplazar
copiando un archivo -> creando una rama
copiar texto al archivo final-> fusionar (fusionar)
copiando los últimos cambios a usted mismo -> git pull / fetch
discusión en correspondencia -> solicitudes de extracción
modo de seguimiento -> git diff
última versión aprobada -> rama maestra
copia de seguridad (copia en un servidor remoto) -> git push
...
Por lo tanto, automatizó todo lo que ya tenía que hacer, pero manualmente.
En un nivel superior, esto te permite
- Cree un proceso claro, simple y controlado para cambiar la documentación.
- porque el documento final (en nuestro ejemplo MS Word) que crea automáticamente, esto reduce la probabilidad de errores relacionados con el formateo
Observación
En vista de lo anterior, creo que es obvio que incluso si está trabajando solo en documentación, el uso de Git puede facilitar enormemente su trabajo
Todo esto mejora la calidad de la documentación y reduce el tiempo de creación. Y una pequeña ventaja: aprendes Git, que te ayudará a automatizar tu red :)
¿Cómo cambiar a un nuevo proceso?
Al comienzo del artículo, escribí que mañana puedes comenzar a trabajar de una manera nueva. ¿Cómo traducir tu trabajo en una nueva dirección?
Aquí está la secuencia de pasos que probablemente tendrá que completar:
- si su documento es muy grande, divídalo en pedazos
- 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 tenga que modificar el formato de los documentos creados de Markdown
- comience a aplicar el proceso descrito en el capítulo anterior
- Paralelamente, comience a modificar el script de conversión para que se ajuste a su tarea (o cree algo propio)
No tiene que esperar hasta crear y depurar perfectamente el mecanismo de conversión Markdwon -> requerido para el tipo de documento de salida. El hecho es que, incluso si no puede automatizar rápidamente la conversión de sus archivos Markdown, puede hacerlo en cualquier forma usando Pandoc y luego llevarlo manualmente a su forma final. Por lo general, no es necesario que haga esto con frecuencia, pero solo al final de ciertas etapas, y este trabajo manual, aunque inconveniente, sigue siendo, en mi opinión, bastante aceptable en la etapa de depuración y no debe ralentizar mucho el proceso.
Todo lo demás (Markdown, Git, Pandoc, Typora) está listo y no requiere esfuerzos especiales o tiempo para comenzar a trabajar con ellos.