Às vezes, não só a documentação em si, mas também o processo de trabalho com ela pode ser crítico. Por exemplo, em projetos, uma grande parte do trabalho está relacionada à preparação da documentação, e um processo inadequado pode levar a erros e até à perda de informações, resultando, portanto, em perda de tempo e lucro. Mas mesmo que este tema não seja central em seu trabalho e esteja na periferia, um processo adequado pode melhorar a qualidade do documento e economizar seu tempo.
A abordagem apresentada aqui, com , tem uma barreira de entrada baixa. Tecnicamente, você pode começar a trabalhar de forma diferente já amanhã.
Formulação do problema
Você precisa criar algum documento ou conjunto de documentos. Pode ser documentação de projeto ou a documentação 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
- esse trabalho envolve um esforço conjunto, a colaboração de um grupo ou vários grupos de funcionários
- no final, você deseja ter um documento em um formato específico, com atributos de estilo corporativo, criado a partir de um determinado modelo. Para ser mais claro, vamos considerar que é um documento MS Word (.docx)
Há 10 anos, a abordagem seria inequívoca: teríamos criado um ou mais documentos MS Word e de alguma forma organizado o trabalho para modificar.
E essa abordagem ainda é válida. Ela é utilizada, inclusive, por grandes integradores na criação de documentação de projeto. Mas é intuitivamente claro que, se você trabalha intensa e continuamente em um documento com muitas revisões e discussões, essa abordagem não é muito conveniente.
Exemplo
Eu percebi agudamente esse problema ao trabalhar em um grande integrador. O processo de modificação da documentação de projeto era o seguinte:
- engenheiro baixa a última versão do documento MS Word (.docx)
- altera o título
- faz modificações no modo de controle de alterações
- envia o documento com as alterações para o arquiteto
- também envia uma lista de todas as correções com comentários
- o arquiteto analisa as modificações
- se tudo estiver certo, copia essas alterações para o arquivo com a última versão, altera a versão e publica no recurso compartilhado
- Se houver comentários, uma discussão será iniciada (por e-mail ou reuniões)
- Consegue-se um consenso
- Em seguida, os itens 3 a 9
Enquanto o trabalho não 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ão é que tudo piora assim que as alterações são feitas com frequência e simultaneamente por várias equipes.
Assim, quando passamos para a fase de testes preliminares, começaram a surgir pequenos problemas e, embora fossem trivialidades, era necessário mudar a documentação com frequência - quatro equipes diferentes, diariamente, praticamente ao mesmo tempo, em discussões. Todas essas mudanças passavam por um engenheiro — arquiteto. O arquivo com o design do projeto era enorme e, como consequência, o arquiteto ficou sobrecarregado com o trabalho rotineiro envolvido em uma grande quantidade de cópias e edições, cometia muitos erros, o que exigia revisões constantes, reenvios e, no geral, isso estava perto do caos.
Neste caso, esse método, o método de trabalhar com o documento MS Word, funcionou com grande dificuldade e gerou problemas.
Git, Markdown
Ao enfrentar o problema descrito no exemplo acima, comecei a investigar essa questão.
Percebi que o uso de em conjunto com na criação de documentos está se tornando cada vez mais popular.
Git é uma ferramenta para desenvolvimento. Mas por que não usá-la para o processo de documentação? Neste caso, a questão do trabalho colaborativo é 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.
Markdown é uma linguagem simples de marcação de texto. Ela é projetada para criar textos bem formatados em arquivos comuns no formato TXT. Se criarmos nossos documentos em Markdown, a combinação Markdown - Git parecerá natural.
E tudo estaria bem, e nesse ponto poderíamos colocar um ponto final, se não fosse pela nossa segunda condição: "precisamos de um documento em um formato específico, com atributos de estilo corporativo, criado de acordo com um determinado modelo" (e concordamos desde o início 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.
Existem programas de conversão entre diferentes formatos, como por exemplo, .
Você pode converter um arquivo Markdown para o formato .docx com este programa.
Mas ainda assim, é importante entender que, em primeiro lugar, nem tudo que existe em Markdown será convertido para o MS Word e, em segundo lugar, o MS Word é um verdadeiro país em comparação com a compacta cidade que é o Markdown. Há uma enorme quantidade de funcionalidades em Word que de nenhuma forma estão disponíveis no Markdown. Não se pode simplesmente pegar e converter seu formato Markdown para o desejado formato MS Word com certas chaves do Pandoc. Portanto, geralmente, após a conversão, é necessário "aprimorar" o documento .docx obtido manualmente, o que, novamente, pode ser dispendioso em termos de tempo e levar a erros.
Se pudéssemos escrever um script que automaticamente "completasse" o que o Pandoc não conseguiu fazer — isso seria a solução ideal.
Devido à não equivalência das funcionalidades do MS Word e do Markdown em geral, acredito que resolver essa tarefa seja impossível, mas seria viável fazer isso em situações específicas, de acordo com exigências concretas? Minha experiência mostrou que sim, é possível e provavelmente isso é viável para muitas, ou talvez até para a maioria das situações.
Solução de uma tarefa específica
Assim, no meu caso, após converter o arquivo com a ajuda do Pandoc, precisei fazer manualmente um processamento adicional nos arquivos, nomeadamente
- adicionar em Word campos com numeração automática de títulos (caption) para tabelas e imagens
- mudar o estilo para tabelas
Não consegui encontrar como fazer isso com as ferramentas padrão (Pandoc) ou conhecidas. Portanto, apliquei um script em python com pacote. Como resultado, obtive uma automação total. Agora posso converter meu arquivo Markdown para o formato necessário de um documento MS Word com um único comando.
Veja os detalhes .
Observação
Neste exemplo, estou, claro, convertendo um arquivo Markdown abstrato, mas a mesma abordagem foi aplicada a um documento 'real', e no final eu obtive praticamente o mesmo documento do MS Word que antes conseguíamos com formatação manual.
Em geral, com pywin32, obtemos praticamente controle total sobre o documento do MS Word, o que nos permite alterá-lo e formatá-lo de acordo com os padrões corporativos. Claro, esses mesmos objetivos poderiam ser alcançados usando outras ferramentas, como macros VBA, mas eu achei mais conveniente usar Python.
A fórmula resumida dessa abordagem é:
Markdown + Git -- (algo) --> MS WordNão importa muito o que é 'algo'. No meu caso, era o Pandoc e Python com pywin32. Você pode ter outras preferências, mas o importante é que isso é possível. E essa é a mensagem principal deste artigo.
Resumindo, a ideia é que, com essa abordagem, você trabalha apenas com o arquivo Markdown e usa o Git para organizar a colaboração e o controle de versões, criando automaticamente o arquivo no formato desejado (por exemplo, MS Word) apenas quando necessário (por exemplo, para fornecer documentação ao cliente).
Processo
Acho que, para muitos, a fórmula acima é suficiente para entender como agora pode ser organizado o processo de trabalho com a documentação. Mas ainda costumo me orientar para engenheiros de redes, por isso vou mostrar, em linhas gerais, como agora pode ser o processo de trabalho e como isso difere da abordagem de edição de arquivos do MS Word.
Para ser mais claro, escolhemos o GitHub como plataforma para trabalhar com o Git. Então você deve criar um repositório e colocar o arquivo ou arquivos Markdown com os quais planeja trabalhar na branch master.
Vamos considerar um processo simples baseado no 'github flow'. Sua descrição pode ser encontrada tanto na internet quanto em .
Suponha que quatro pessoas estão trabalhando na documentação e você é uma delas. Então são criadas quatro branches adicionais, por exemplo, com os nomes dessas pessoas. Cada um trabalha localmente em sua branch e faz alterações com todos os comandos necessários do .
Ao concluir uma parte específica do trabalho, você cria um pull request, iniciando assim a discussão sobre suas mudanças. Durante o processo de discussão, pode-se descobrir que você precisa adicionar ou modificar algo mais. Nesse caso, você faz as alterações necessárias e cria um pull request adicional. Por fim, suas mudanças são aceitas e mescladas (merge) com a branch master (ou rejeitadas).
Claro, essa é uma descrição bastante geral. Sugiro que para criar um processo detalhado, você converse com seus desenvolvedores ou encontre pessoas conhecedoras. Mas quero ressaltar que a barreira de entrada para o Git é bem baixa. Isso não significa que o protocolo seja simples, mas você pode começar de forma simples. Se você não sabe nada, penso que, gastando algumas horas ou talvez dias estudando e instalando, você poderá começar a usá-lo.
Qual é a vantagem desse approach em comparação, por exemplo, ao processo descrito no exemplo acima?
Na verdade, os processos são bastante semelhantes, você apenas substituiu
cópia de arquivo -> criação de branch
cópia de texto no arquivo final -> mesclagem
cópia das últimas alterações para o seu repositório -> git pull/fetch
discussão por meio de mensagens -> pull requests
modo de acompanhamento -> git diff
última versão aprovada -> branch master
backup (cópia no servidor remoto) -> git push
…
Assim, você automatizou tudo o que já precisava fazer, mas manualmente.
Em um nível mais alto, isso permite que você
- crie um processo claro, simples e controlável para as alterações da documentação
- já que o documento final (no nosso exemplo, o MS Word) é criado automaticamente, isso reduz a probabilidade de erros relacionados à formatação.
Observação
Dado o que foi dito acima, penso ser óbvio que, mesmo que você trabalhe sozinho na documentação, o uso do Git pode facilitar consideravelmente seu trabalho.
Tudo isso melhora a qualidade da documentação e reduz o tempo necessário para criá-la. E um pequeno bônus — você vai aprender Git, o que ajudará na automação da sua rede 🙂
Como migrar para o novo processo?
No início do artigo, mencionei que você pode começar a trabalhar de forma diferente já amanhã. Como direcionar seu trabalho para esse novo fluxo?
Aqui está a sequência de passos que você provavelmente precisará seguir:
- se seu documento for muito extenso, divida-o em partes.
- converta cada parte para Markdown (usando o Pandoc, por exemplo)
- instale um dos editores de Markdown (eu uso )
- provavelmente você precisará ajustar a formatação dos documentos Markdown criados
- comece a aplicar o processo descrito no capítulo anterior
- simultaneamente comece a modificar o script de conversão para sua tarefa (ou crie algo próprio)
Você não precisa esperar até que crie e depure perfeitamente o mecanismo de conversão Markdown -> o formato de documento desejado. A questão é que, mesmo que você não consiga automatizar rapidamente todo o processo de conversão dos seus arquivos Markdown, ainda assim poderá fazê-lo de alguma maneira com o Pandoc e, em seguida, finalizá-lo manualmente. Normalmente, você não precisa fazer isso com frequência, apenas no final de certas etapas, e esse trabalho manual, embora inconveniente, é aceitável na fase de depuração e não deve 'atrapalhar' muito o processo.
Todo o resto (Markdown, Git, Pandoc, Typora) já está pronto e não requer esforços ou tempo especiais para começar a trabalhar com eles.
Fonte: habr.com
