{"id":35419,"date":"2019-10-31T22:04:14","date_gmt":"2019-10-31T19:04:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/ispolzujte-git-pri-dokumentirovanii\/"},"modified":"2019-10-31T22:04:14","modified_gmt":"2019-10-31T19:04:14","slug":"ispolzujte-git-pri-dokumentirovanii","status":"publish","type":"post","link":"https:\/\/prohoster.info\/es\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Utiliza GIT para la documentaci\u00f3n","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

A veces, no solo la documentaci\u00f3n en s\u00ed, sino tambi\u00e9n el proceso de trabajo sobre ella puede ser cr\u00edtico. Por ejemplo, en proyectos, gran parte del trabajo est\u00e1 relacionada precisamente con la preparaci\u00f3n de la documentaci\u00f3n, y un proceso incorrecto puede llevar a errores e incluso a la p\u00e9rdida de informaci\u00f3n, lo que a su vez resulta en p\u00e9rdida de tiempo y ganancias. Pero incluso si este tema no es central en tu trabajo y est\u00e1 en la periferia, un proceso adecuado puede mejorar la calidad del documento y ahorrarte tiempo.<\/p>\n

El enfoque aqu\u00ed presentado, con un ejemplo de implementaci\u00f3n concreta<\/a><\/noindex>, tiene un bajo umbral de entrada. T\u00e9cnicamente, ya ma\u00f1ana puedes comenzar a trabajar de una manera diferente.
\n<\/a><\/noindex><\/p>\n

Planteamiento del problema<\/h3>\n

\nNecesitas crear alg\u00fan documento o conjunto de documentos. Puede que sea documentaci\u00f3n de proyecto o registro de tu red, o algo m\u00e1s 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\u00e1genes, tablas\u2026 Complicaremos la tarea en el sentido de que <\/p>\n

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

    \nHace 10 a\u00f1os, el enfoque habr\u00eda sido claro: habr\u00edamos creado un documento en MS Word y de alguna manera organizado el trabajo de modificaci\u00f3n. <\/p>\n

    Y ese enfoque sigue en vigor. Tambi\u00e9n lo utilizan grandes integradores para crear documentaci\u00f3n de proyecto. Pero intuitivamente se comprende que, si realmente trabajas intensivamente, con muchas modificaciones y discusiones, durante un per\u00edodo prolongado sobre un documento, este enfoque no es muy conveniente.<\/p>\n

    Ejemplo<\/b><\/p>\n

    Sent\u00ed agudamente este problema al trabajar en un gran integrador. El proceso de modificaci\u00f3n de la documentaci\u00f3n del proyecto era el siguiente:<\/p>\n

      \n
    1. el ingeniero descarga la \u00faltima versi\u00f3n del documento de MS Word (.docx)<\/li>\n
    2. cambia el nombre<\/li>\n
    3. hace modificaciones en modo de seguimiento<\/li>\n
    4. env\u00eda el documento con las modificaciones al arquitecto<\/li>\n
    5. tambi\u00e9n env\u00eda una lista de todas las correcciones con comentarios<\/li>\n
    6. el arquitecto analiza los cambios<\/li>\n
    7. si todo est\u00e1 bien, copia los cambios de datos en el archivo con la \u00faltima versi\u00f3n, cambia la versi\u00f3n y lo publica en un recurso com\u00fan<\/li>\n
    8. si hay comentarios, se inicia una discusi\u00f3n (por correo electr\u00f3nico o reuniones)<\/li>\n
    9. se alcanza un consenso<\/li>\n
    10. a continuaci\u00f3n, los puntos 3 a 9<\/li>\n<\/ol>\n

      \nMientras el trabajo no era intenso, esto funcionaba m\u00e1s o menos. Pero en cierto momento, este proceso se convirti\u00f3 en un cuello de botella para todo el proyecto y caus\u00f3 problemas. La cuesti\u00f3n es que todo se complica en cuanto los cambios se realizan con frecuencia y simult\u00e1neamente por varios equipos.<\/p>\n

      As\u00ed que, cuando pasamos a la etapa de prueba previa, comenzaron a aparecer varios problemas y, aunque menores, era necesario cambiar la documentaci\u00f3n con frecuencia \u2014 cuatro equipos diferentes, diariamente, pr\u00e1cticamente al mismo tiempo, con discusiones. Todos estos cambios pasaban por un solo ingeniero \u2014 arquitecto. El archivo del dise\u00f1o 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\u00eda muchos errores, hab\u00eda que verificar todo nuevamente, re-enviar, y en general, se acercaba al caos. <\/p>\n

      En este caso, este enfoque, el enfoque de trabajo con el documento MS Word, funcionaba con gran dificultad y creaba problemas.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nEnfrentado con el problema descrito en el ejemplo anterior, comenc\u00e9 a investigar este tema.
      \nVi que el uso de       Markdown<\/a><\/noindex> junto con Git<\/a><\/noindex> est\u00e1 ganando popularidad en la creaci\u00f3n de documentos.<\/p>\n

      Git es una herramienta para el desarrollo. Pero, \u00bfpor qu\u00e9 no usarla para el proceso de documentaci\u00f3n? En este caso, la cuesti\u00f3n del trabajo colaborativo queda resuelta. Pero para aprovechar al m\u00e1ximo 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. <\/p>\n

      Markdown es un lenguaje de marcado de texto sencillo. Est\u00e1 dise\u00f1ado para crear textos bien formateados en archivos de formato TXT. Si creamos nuestros documentos en Markdown, la combinaci\u00f3n Markdown - Git parece natural.<\/p>\n

      Y todo estar\u00eda bien, y en este punto podr\u00edamos poner un punto final, si no fuera por nuestra segunda condici\u00f3n: \"necesitamos un documento en un formato espec\u00edfico, con atributos de estilo corporativo, creado seg\u00fan una plantilla determinada\" (y acordamos al principio que, para ser precisos, esto ser\u00eda MS Word). Es decir, si decidimos usar Markdown, necesitamos de alguna manera convertir este archivo en el .docx requerido.<\/p>\n

      Existen programas de conversi\u00f3n entre diferentes formatos, por ejemplo, Pandoc<\/a><\/noindex>.
      \nPuede convertir un archivo Markdown al formato .docx con este programa.
      \nSin embargo, hay que entender que, en primer lugar, no todo lo que hay en Markdown se convertir\u00e1 a MS Word y, en segundo lugar, MS Word es todo un pa\u00eds en comparaci\u00f3n con la ordenada, pero a\u00fan as\u00ed peque\u00f1a ciudad de Markdown. Hay una cantidad enorme de cosas que est\u00e1n en Word y no existen en ning\u00fan formato de Markdown. No se puede simplemente convertir su formato Markdown al deseado MS Word con ciertas claves de Pandoc. Por lo general, despu\u00e9s de la conversi\u00f3n, es necesario \"completar\" el documento .docx obtenido manualmente, lo cual tambi\u00e9n puede ser costoso en t\u00e9rminos de tiempo y llevar a errores.<\/p>\n

      Si pudi\u00e9ramos escribir un script que autom\u00e1ticamente \"completara\" lo que Pandoc no pudo manejar, ser\u00eda la soluci\u00f3n ideal.<\/p>\n

      Debido a que la funcionalidad de MS Word y Markdown no son equivalentes en general, creo que resolver esta tarea es imposible, pero \u00bfse puede hacer aplicable a situaciones concretas, a requisitos espec\u00edficos? Mi experiencia ha demostrado que s\u00ed, se puede, y es probable que esto sea posible para muchas, o incluso la mayor\u00eda de las situaciones. <\/p>\n

      Soluci\u00f3n de un problema espec\u00edfico<\/h3>\n

      \nAs\u00ed que, en mi caso, despu\u00e9s de convertir el archivo usando Pandoc, ten\u00eda que hacer un procesamiento adicional de los archivos manualmente, es decir,<\/p>\n