{"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\/pt\/blog\/administrirovanie\/ispolzujte-git-pri-dokumentirovanii","title":{"rendered":"Use GIT ao documentar","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

\u00c0s vezes, n\u00e3o s\u00f3 a documenta\u00e7\u00e3o em si, mas tamb\u00e9m o processo de trabalho com ela pode ser cr\u00edtico. Por exemplo, em projetos, uma grande parte do trabalho est\u00e1 relacionada \u00e0 prepara\u00e7\u00e3o da documenta\u00e7\u00e3o, e um processo inadequado pode levar a erros e at\u00e9 \u00e0 perda de informa\u00e7\u00f5es, resultando, portanto, em perda de tempo e lucro. Mas mesmo que este tema n\u00e3o seja central em seu trabalho e esteja na periferia, um processo adequado pode melhorar a qualidade do documento e economizar seu tempo.<\/p>\n

A abordagem apresentada aqui, com um exemplo de implementa\u00e7\u00e3o espec\u00edfica<\/a><\/noindex>, tem uma barreira de entrada baixa. Tecnicamente, voc\u00ea pode come\u00e7ar a trabalhar de forma diferente j\u00e1 amanh\u00e3.
\n<\/a><\/noindex><\/p>\n

Formula\u00e7\u00e3o do problema<\/h3>\n

\nVoc\u00ea precisa criar algum documento ou conjunto de documentos. Pode ser documenta\u00e7\u00e3o de projeto ou a documenta\u00e7\u00e3o da sua rede, ou algo mais simples, como descrever processos na empresa ou no seu departamento. Em resumo, trata-se de qualquer documento ou conjunto de documentos com texto, imagens, tabelas... Vamos complicar a tarefa dizendo que <\/p>\n

    \n
  1. esse trabalho envolve um esfor\u00e7o conjunto, a colabora\u00e7\u00e3o de um grupo ou v\u00e1rios grupos de funcion\u00e1rios<\/li>\n
  2. no final, voc\u00ea deseja ter um documento em um formato espec\u00edfico, com atributos de estilo corporativo, criado a partir de um determinado modelo. Para ser mais claro, vamos considerar que \u00e9 um documento MS Word (.docx)<\/li>\n<\/ol>\n

    \nH\u00e1 10 anos, a abordagem seria inequ\u00edvoca: ter\u00edamos criado um ou mais documentos MS Word e de alguma forma organizado o trabalho para modificar. <\/p>\n

    E essa abordagem ainda \u00e9 v\u00e1lida. Ela \u00e9 utilizada, inclusive, por grandes integradores na cria\u00e7\u00e3o de documenta\u00e7\u00e3o de projeto. Mas \u00e9 intuitivamente claro que, se voc\u00ea trabalha intensa e continuamente em um documento com muitas revis\u00f5es e discuss\u00f5es, essa abordagem n\u00e3o \u00e9 muito conveniente.<\/p>\n

    Exemplo<\/b><\/p>\n

    Eu percebi agudamente esse problema ao trabalhar em um grande integrador. O processo de modifica\u00e7\u00e3o da documenta\u00e7\u00e3o de projeto era o seguinte:<\/p>\n

      \n
    1. engenheiro baixa a \u00faltima vers\u00e3o do documento MS Word (.docx)<\/li>\n
    2. altera o t\u00edtulo<\/li>\n
    3. faz modifica\u00e7\u00f5es no modo de controle de altera\u00e7\u00f5es<\/li>\n
    4. envia o documento com as altera\u00e7\u00f5es para o arquiteto<\/li>\n
    5. tamb\u00e9m envia uma lista de todas as corre\u00e7\u00f5es com coment\u00e1rios<\/li>\n
    6. o arquiteto analisa as modifica\u00e7\u00f5es<\/li>\n
    7. se tudo estiver certo, copia essas altera\u00e7\u00f5es para o arquivo com a \u00faltima vers\u00e3o, altera a vers\u00e3o e publica no recurso compartilhado<\/li>\n
    8. Se houver coment\u00e1rios, uma discuss\u00e3o ser\u00e1 iniciada (por e-mail ou reuni\u00f5es)<\/li>\n
    9. Consegue-se um consenso<\/li>\n
    10. Em seguida, os itens 3 a 9<\/li>\n<\/ol>\n

      \nEnquanto o trabalho n\u00e3o foi intenso, isso funcionou de alguma forma. Mas, em determinado momento, esse processo se tornou o gargalo do projeto inteiro e levou a problemas. A quest\u00e3o \u00e9 que tudo piora assim que as altera\u00e7\u00f5es s\u00e3o feitas com frequ\u00eancia e simultaneamente por v\u00e1rias equipes.<\/p>\n

      Assim, quando passamos para a fase de testes preliminares, come\u00e7aram a surgir pequenos problemas e, embora fossem trivialidades, era necess\u00e1rio mudar a documenta\u00e7\u00e3o com frequ\u00eancia - quatro equipes diferentes, diariamente, praticamente ao mesmo tempo, em discuss\u00f5es. Todas essas mudan\u00e7as passavam por um engenheiro \u2014 arquiteto. O arquivo com o design do projeto era enorme e, como consequ\u00eancia, o arquiteto ficou sobrecarregado com o trabalho rotineiro envolvido em uma grande quantidade de c\u00f3pias e edi\u00e7\u00f5es, cometia muitos erros, o que exigia revis\u00f5es constantes, reenvios e, no geral, isso estava perto do caos. <\/p>\n

      Neste caso, esse m\u00e9todo, o m\u00e9todo de trabalhar com o documento MS Word, funcionou com grande dificuldade e gerou problemas.<\/p><\/blockquote>\n

      <\/p>\n

      Git, Markdown<\/h3>\n

      \nAo enfrentar o problema descrito no exemplo acima, comecei a investigar essa quest\u00e3o.
      \nPercebi que o uso de       Markdown<\/a><\/noindex> em conjunto com Git<\/a><\/noindex> na cria\u00e7\u00e3o de documentos est\u00e1 se tornando cada vez mais popular.<\/p>\n

      Git \u00e9 uma ferramenta para desenvolvimento. Mas por que n\u00e3o us\u00e1-la para o processo de documenta\u00e7\u00e3o? Neste caso, a quest\u00e3o do trabalho colaborativo \u00e9 resolvida. Mas para aproveitar totalmente as capacidades do Git, precisamos de um formato de documento textual, precisamos encontrar outra ferramenta, diferente do MS Word, e o Markdown se encaixa muito bem para esses fins. <\/p>\n

      Markdown \u00e9 uma linguagem simples de marca\u00e7\u00e3o de texto. Ela \u00e9 projetada para criar textos bem formatados em arquivos comuns no formato TXT. Se criarmos nossos documentos em Markdown, a combina\u00e7\u00e3o Markdown - Git parecer\u00e1 natural.<\/p>\n

      E tudo estaria bem, e nesse ponto poder\u00edamos colocar um ponto final, se n\u00e3o fosse pela nossa segunda condi\u00e7\u00e3o: \"precisamos de um documento em um formato espec\u00edfico, com atributos de estilo corporativo, criado de acordo com um determinado modelo\" (e concordamos desde o in\u00edcio que, para maior clareza, isso seria MS Word). Ou seja, se decidimos usar Markdown, precisamos de alguma forma converter este arquivo em .docx no formato exigido.<\/p>\n

      Existem programas de convers\u00e3o entre diferentes formatos, como por exemplo, Pandoc<\/a><\/noindex>.
      \nVoc\u00ea pode converter um arquivo Markdown para o formato .docx com este programa.
      \nMas ainda assim, \u00e9 importante entender que, em primeiro lugar, nem tudo que existe em Markdown ser\u00e1 convertido para o MS Word e, em segundo lugar, o MS Word \u00e9 um verdadeiro pa\u00eds em compara\u00e7\u00e3o com a compacta cidade que \u00e9 o Markdown. H\u00e1 uma enorme quantidade de funcionalidades em Word que de nenhuma forma est\u00e3o dispon\u00edveis no Markdown. N\u00e3o se pode simplesmente pegar e converter seu formato Markdown para o desejado formato MS Word com certas chaves do Pandoc. Portanto, geralmente, ap\u00f3s a convers\u00e3o, \u00e9 necess\u00e1rio \"aprimorar\" o documento .docx obtido manualmente, o que, novamente, pode ser dispendioso em termos de tempo e levar a erros.<\/p>\n

      Se pud\u00e9ssemos escrever um script que automaticamente \"completasse\" o que o Pandoc n\u00e3o conseguiu fazer \u2014 isso seria a solu\u00e7\u00e3o ideal.<\/p>\n

      Devido \u00e0 n\u00e3o equival\u00eancia das funcionalidades do MS Word e do Markdown em geral, acredito que resolver essa tarefa seja imposs\u00edvel, mas seria vi\u00e1vel fazer isso em situa\u00e7\u00f5es espec\u00edficas, de acordo com exig\u00eancias concretas? Minha experi\u00eancia mostrou que sim, \u00e9 poss\u00edvel e provavelmente isso \u00e9 vi\u00e1vel para muitas, ou talvez at\u00e9 para a maioria das situa\u00e7\u00f5es. <\/p>\n

      Solu\u00e7\u00e3o de uma tarefa espec\u00edfica<\/h3>\n

      \nAssim, no meu caso, ap\u00f3s converter o arquivo com a ajuda do Pandoc, precisei fazer manualmente um processamento adicional nos arquivos, nomeadamente<\/p>\n