Às vezes, não apenas a documentação em si, mas também o processo de trabalhar nela pode ser crítico. Por exemplo, no caso de projetos, a parte principal do trabalho está relacionada à preparação da documentação, e um processo incorreto pode levar a erros e até perda de informações e, consequentemente, perda de tempo e lucro. Mas, mesmo que esse tópico não seja central no seu trabalho e esteja localizado na periferia, o processo correto ainda poderá melhorar a qualidade do documento e economizar tempo.
A abordagem descrita aqui, com
um exemplo de uma implementação específica , tem um limite baixo de entrada. Tecnicamente, amanhã você pode começar a trabalhar de uma nova maneira.
Declaração do problema
Você precisa criar um determinado documento ou um conjunto de documentos. Talvez seja a documentação do projeto ou o log da sua rede, ou algo mais simples, por exemplo, você deve descrever os processos na empresa ou no seu departamento. Em geral, estamos falando de qualquer documento ou conjunto de documentos com texto, figuras, placas ... Nós complicamos a tarefa pelo fato de que
- esse trabalho envolve trabalho conjunto, os esforços de um grupo ou de vários grupos de funcionários
- Na saída, você deseja ter um documento em um formato específico, com atributos de estilo corporativo, criado de acordo com um modelo específico. Por definição, assumiremos que este é o MS Word (.docx)
Há 10 anos, a abordagem seria inequívoca: criaríamos um documento ou documentos do MS Word e, de alguma forma, organizaríamos o trabalho sobre a mudança.
E essa abordagem ainda é válida. Também é usado por grandes integradores ao criar a documentação do projeto. Mas é intuitivamente claro que, se você é realmente intensivo, com muitas edições e discussões, durante muito tempo trabalhando em um documento, essa abordagem não é muito conveniente.
Exemplo
Senti esse problema de maneira aguda enquanto trabalhava em um grande integrador. O processo de alteração da documentação do design foi o seguinte:
- engenheiro baixa a versão mais recente do documento MS Word (.docx)
- muda o nome
- faz alterações no mod de pista
- envia o documento com correções para o arquiteto
- também envia uma lista de todas as correções com comentários
- arquiteto analisa mudanças
- se estiver tudo bem, copie os dados alterados para o arquivo com a versão mais recente, altere a versão e os coloque em um recurso compartilhado
- se houver comentários, uma discussão será iniciada (email ou comícios)
- consenso é alcançado
- parágrafos 3 - 9 adicionais
Enquanto o trabalho não era intenso, de alguma forma, mas ainda funcionava. Mas, em determinado momento, esse processo se tornou o gargalo de todo o projeto e levou a problemas. O fato é que tudo fica ruim assim que as mudanças são feitas frequentemente e simultaneamente por várias equipes.
Então, quando chegamos à fase de testes preliminares, vários problemas começaram a aparecer e, embora nos detalhes, tivemos que alterar a documentação com frequência - quatro equipes diferentes, diariamente, quase simultaneamente, com discussões. Todas essas mudanças passaram por um engenheiro - um arquiteto. O arquivo com o design do projeto era enorme e, como resultado, o arquiteto ficou sobrecarregado com o trabalho de rotina associado a muitas cópias, edições, cometeu muitos erros, tive que verificar novamente, reenviar e, em geral, estava perto do caos.
Nesse caso, essa abordagem, a abordagem de trabalhar em um documento do MS Word, funcionou com grande ruído e criou problemas.
Remarcação Git
Diante do problema descrito no exemplo acima, comecei a pesquisar esse problema.
Vi que o uso do
Markdown com o
Git durante a criação de documentos está se tornando cada vez mais popular.
Git é uma ferramenta de desenvolvimento. Mas por que não usá-lo para o processo de documentação? Nesse caso, a questão do trabalho multiusuário é resolvida. Mas, para fazer pleno uso dos recursos do Git, precisamos de um formato de texto para o documento, precisamos encontrar outra ferramenta, não o MS Word, e o Markdown é ótimo para esses propósitos.
Markdown é uma linguagem simples de marcação de texto. Ele foi projetado para criar textos lindamente projetados em arquivos TXT regulares. Se criarmos nossos documentos no Markdown, o link Markdown-Git parecerá natural.
E tudo ficaria bem e, nesse local, seria possível pôr um fim se não fosse a nossa segunda condição: "na saída, precisamos de um documento em um determinado formato, com atributos de estilo corporativo criados de acordo com um determinado modelo" (e concordamos que, para certeza, será o MS Word). Ou seja, se decidimos usar o Markdown, precisamos converter de alguma forma esse arquivo em .docx do tipo necessário.
Existem programas para converter entre diferentes formatos, por exemplo,
Pandoc .
Você pode converter o arquivo Markdown para o formato .docx com este programa.
Mas, ainda assim, você precisa entender que, em primeiro lugar, nem tudo o que está no Markdown será convertido para o MS Word e, em segundo lugar, o MS Word é um país inteiro comparado à cidade pequena, mas ainda pequena, Markdown. Existe uma quantidade enorme de tudo o que está no Word e de nenhuma forma está no Markdown. Você não pode simplesmente levar o seu formato Markdown com as chaves Pandoc desejadas para o formato desejado do MS Word. Então, geralmente, após a conversão, você precisa "refinar" o documento .docx recebido manualmente, o que pode ser demorado e levar a erros.
Se pudéssemos escrever um script que "terminasse" automaticamente o que Pandoc não poderia fazer, seria uma solução ideal.
Devido ao fato de que a funcionalidade do MS Word e Markdown não é idêntica em termos gerais, acho que é impossível resolver esse problema, mas isso pode ser feito em relação a situações específicas, requisitos específicos? Minha experiência demonstrou que sim, é possível e provavelmente é possível para muitas, ou talvez até para a maioria das situações.
Solução de um problema específico
Portanto, no meu caso, depois de converter o arquivo usando o Pandoc, tive que fazer manualmente um processamento adicional, a saber
- adicione campos no Word com numeração automática de legendas de tabelas e imagens
- mude o estilo para tabelas
Não encontrei como fazer isso usando meios padrão (Pandoc) ou conhecidos. Portanto, apliquei um script python com o pacote
pywin32 . Como resultado, obtive automação completa. Agora eu posso converter meu arquivo Markdown para a forma desejada do documento do MS Word com um comando.
Veja detalhes
aqui .
Observação
Neste exemplo, eu, é claro, converterei algum arquivo Markdown abstrato, mas exatamente a mesma abordagem foi aplicada ao documento de "combate" e, na saída, recebi quase exatamente o mesmo documento do MS Word, que recebemos anteriormente por formatação manual.
Em geral, com o pywin32, obtemos controle quase completo sobre o documento do MS Word, o que nos permite alterá-lo e trazê-lo à aparência exigida pelo seu padrão corporativo. Obviamente, os mesmos objetivos poderiam ser alcançados usando outras ferramentas, por exemplo, macros VBA, mas era mais conveniente para mim usar python.
Uma breve fórmula para essa abordagem:
Markdown + Git -- () --> MS Word
Não é tão importante o que "algo" é. No meu caso, foi Pandoc e python com pywin32. Você pode ter preferências diferentes, mas o importante é que isso seja possível. E esta é a principal mensagem deste artigo.
Em resumo, a idéia é que, com essa abordagem, você trabalhe apenas com o arquivo Markdown e use o Git para organizar a colaboração e o controle de versão e somente se necessário (por exemplo, para fornecer documentação ao cliente) crie automaticamente o arquivo no formato desejado (por exemplo, MS Word )
O processo
Para muitos, a fórmula acima é suficiente para entender como o processo de trabalhar com a documentação pode ser organizado agora. Mas, no entanto, eu geralmente me concentro em engenheiros de rede, portanto, descreverei em geral como o processo pode parecer agora e como difere da abordagem para editar arquivos do MS Word.
Por definição, escolheremos o GitHub como a plataforma para trabalhar com o Git. Em seguida, você deve criar um repositório e colocar o arquivo ou arquivos Markdown com os quais planeja trabalhar na ramificação principal.
Veremos um processo simples baseado no fluxo do github. Sua descrição pode ser encontrada na Internet e no
Habr .
Suponha que quatro pessoas estejam trabalhando na documentação e você seja uma delas. Em seguida, quatro ramificações adicionais são criadas, por exemplo, com os nomes dessas pessoas. Cada um trabalha localmente, em sua própria ramificação e faz alterações com todos os
comandos git necessários.
Depois de concluir algumas tarefas concluídas, você forma uma solicitação de recebimento, iniciando uma discussão sobre suas alterações. Talvez no processo de discussão, você deva adicionar ou alterar outra coisa. Nesse caso, você faz as alterações necessárias e cria uma solicitação de recebimento adicional. No final, suas alterações são aceitas e mescladas com a ramificação principal (ou rejeitadas).
Obviamente, esta é uma descrição bastante geral. Sugiro entrar em contato com seus desenvolvedores ou encontrar pessoas com conhecimento para criar um processo detalhado. Mas quero observar que o limite para entrar no Git é bastante baixo. Isso não significa que o protocolo seja simples, mas você pode começar com um simples. Se você não sabe nada, eu acho, depois de passar várias horas ou talvez dias para estudar e instalar, você pode começar a usá-lo.
Qual é a utilidade dessa abordagem em comparação, por exemplo, com o processo descrito no exemplo acima?
Na verdade, os processos são bem parecidos, você acabou de substituir
copiando um arquivo -> criando uma ramificação
copiar texto para o arquivo final-> mesclar (mesclar)
copiando as alterações mais recentes para você mesmo -> git pull / fetch
discussão em correspondência -> solicitações pull
modo de faixa -> diff git
versão mais recente aprovada -> ramificação principal
backup (copiando para um servidor remoto) -> git push
...
Assim, você automatizou tudo o que já tinha que fazer, mas manualmente.
Em um nível superior, isso permite que você
- Crie um processo claro, simples e controlado para alterar a documentação.
- porque o documento final (em nosso exemplo, MS Word) que você cria automaticamente, reduz a probabilidade de erros relacionados à formatação
Observação
Tendo em vista o exposto, acho óbvio que, mesmo se você estiver trabalhando apenas na documentação, o uso do Git poderá facilitar muito o seu trabalho.
Tudo isso melhora a qualidade da documentação e reduz o tempo para sua criação. E um pouco de bônus - você aprende Git, que o ajudará a automatizar sua rede :)
Como mudar para um novo processo?
No começo do artigo, escrevi que amanhã você poderá começar a trabalhar de uma nova maneira. Como traduzir seu trabalho em uma nova direção?
Aqui está a sequência de etapas que você provavelmente precisará concluir:
- se o seu documento for muito grande, divida-o em pedaços
- converta cada parte em Markdown (usando Pandoc, por exemplo)
- instale um dos editores do Markdown (eu uso o Typora )
- provavelmente você precisará ajustar a formatação dos documentos Markdown criados
- comece a aplicar o processo descrito no capítulo anterior
- paralelamente, comece a modificar o script de conversão para se adequar à sua tarefa (ou crie algo de sua preferência)
Você não precisa esperar até criar e depurar perfeitamente o mecanismo de conversão Markdwon -> necessário para o tipo de documento de saída. O fato é que, mesmo que você não consiga automatizar rapidamente a conversão dos arquivos do Markdown rapidamente, você ainda pode fazer isso de qualquer forma usando o Pandoc e trazê-lo manualmente para a forma final. Geralmente, você não precisa fazer isso com frequência, mas apenas no final de certos estágios, e este trabalho manual, embora inconveniente, ainda é, na minha opinião, bastante aceitável no estágio de depuração e não deve desacelerar muito o processo.
Todo o resto (Markdown, Git, Pandoc, Typora) está pronto e não requer esforços ou tempo especiais para começar a trabalhar com eles.