Boa tarde
Como um dos desenvolvedores do projeto de código-fonte
Embox , ouvi muitas vezes (com muita frequência ultimamente) que o projeto é interessante, mas como não há documentação, ele não pode ser usado. Respondemos que havia algum tipo de documentação, que sempre podemos responder perguntas e que, em casos extremos, você pode tentar descobrir por conta própria, porque o projeto é aberto, mas tudo isso não se encaixava. Eu tive que lidar com esse tópico muito desagradável para desenvolvedores. Mas, naturalmente, o artigo não trata do fato de que a documentação é "desagradável"! E sobre como tornamos o processo de desenvolvimento de documentação mais confortável. De fato, em qualquer projeto mais ou menos grande, necessariamente surgem questões relacionadas à documentação.
Para quem tem preguiça de ler, direi imediatamente que, no final, chegamos ao desenvolvimento da documentação em formato de remarcação. Bem, para aqueles que estão interessados nos detalhes, nas razões pelas quais o markdown e quais são os prós e os contras dessa abordagem, peço gato.
Começarei justificando a relevância do tópico. Não apenas a Embox tem problemas de documentação. Por exemplo, o Google anunciou uma analogia do programa Google Summer Of Code (GSOC) para redatores técnicos,
Season of Docs . A empresa da Kaspersky Lab realiza
conferências para redatores técnicos . E a empresa Parallels publica
artigos no hub sobre como escrever documentação . Tudo isso indica que o tópico é importante e talvez imerecidamente privado de atenção.
A série de artigos mencionados acima compreende o conteúdo correto da documentação, mas quero focar no processo de desenvolvimento de documentação, tecnologia, se você desejar. De fato, para um projeto de código aberto, a marca registrada é a abertura como uma propriedade do processo de desenvolvimento. E queríamos criar um processo que satisfizesse os requisitos do nosso projeto.
Uma breve digressão no histórico de nossos processos de desenvolvimento de documentação.
Depois que o projeto foi localizado no
código de
googl . Nós tínhamos um wiki bastante decente, muitos até lembram dele, perguntam onde encontrá-lo e pedem para transferi-lo para o github, onde o projeto está localizado agora (ou em outro local acessível). O wiki do googlecode foi realmente útil. Era multilíngue e tinha, na minha opinião, mais recursos do que o wiki no github. Mas aconteceu que, junto com o próprio código de googl, caiu no esquecimento. O wiki atual no github executa muito bem a função atribuída a ele de fornecer informações operacionais sobre o projeto, mas é bastante difícil criar documentação completa nesta plataforma.
Obviamente, para qualquer projeto de código aberto, você precisa de documentação on-line (acessível rapidamente), cuja função é desempenhada pelo wiki, e de documentação completa disponível off-line, porque é muito mais fácil entender a essência e a ideologia do projeto. Além disso, fazer pesquisas offline em um único documento, em vez de páginas wiki diferentes, também é muito mais fácil.
Provavelmente a melhor opção que conheço é a
documentação do
ARM . Ou seja, documentação on-line, onde há uma pesquisa em todas as seções, mas um documento específico está disponível para download em formato pdf. Infelizmente, a Embox ainda não atingiu o nível de ARM em termos de recursos. Portanto, tivemos que fazer a versão offline separadamente. Para isso, usamos o serviço
Google Docs . É conveniente porque: permite baixar dados em vários formatos, colaborar e possui um sistema de controle de versão embutido. Transferimos algumas das informações do wiki, definimos a estrutura, porque o objetivo do desenvolvimento da versão offline era criar documentação holística e começamos a desenvolver vários documentos. Mas rápido o suficiente, tivemos problemas. As informações estavam desatualizadas, os dados do wiki não correspondiam aos da documentação offline e, o mais importante, não conseguimos criar a documentação completa. Havia uma estrutura, mas como não era possível obter feedback decente dos usuários, descobriu-se que apenas seus criadores podem entender a documentação. Esse certamente não é um problema de serviço, mas o fato, como eles dizem, é óbvio. Tivemos que procurar uma abordagem diferente para esse problema.
Em seguida, tentamos transferir os dados do wiki antigo para o github, mas mesmo assim rapidamente enfrentamos problemas. Descobrimos que parte da informação está desatualizada, parte não foi adicionada, parte não ficou clara como apresentá-la de forma amigável. Continuando a busca por uma solução para o problema, em algum momento, até consideramos o desenvolvimento de documentação no TeX usando o repositório git, mas rapidamente percebemos que isso já era demais. Embora essa ideia tenha tido um impacto.
Decidimos formular o que queremos da documentação, ou seja, do processo de desenvolvimento da documentação, deixamos o conteúdo fora dos colchetes:
- A documentação deve ser mantida em formato de texto, pois deveria usar o git como um sistema de controle de versão
- A documentação deve ter versões online (wiki) e offline (documentos separados, por exemplo, em pdf)
- A documentação online e offline deve poder sincronizar facilmente.
- A documentação deve consistir em seções (capítulos) que podem ser desenvolvidas ou estudadas separadamente, mas a partir da qual você pode compor a documentação completa
Nenhum dos pontos contradiz o uso da remarcação, e foi interessante, pois já é usado no wiki. Obviamente, você pode usar um formato diferente e convertê-lo em descontos. Mas, depois de compilar outra lista de requisitos, desta vez com a capacidade de adicionar vários tipos de conteúdo (imagens, texto, formatação), chegamos à conclusão de que a redução satisfaz suficientemente todas as nossas necessidades atuais. E o primeiro google no tópico "remarcação para pdf" mostrou que as opções para converter remarcações para outros formatos existem e são bastante populares.
Existem várias opções para transformar a redução em pdf , mas o
pandoc é de
longe o mais popular. Este utilitário pode transformar qualquer formato de texto em qualquer formato de texto. Além disso, é cantilever. Portanto, não é apenas familiar para nós, mas também pode ser incorporado em scripts para criar documentação em vários formatos.
Decidimos sobre o utilitário e começamos a pensar na próxima pequena pergunta que precisávamos resolver, como criar um único documento, e não muitos arquivos PDF com capítulos diferentes, obtidos de arquivos de remarcação separados. O primeiro desejo era simplesmente “salvar” os arquivos (mesclar texto de vários arquivos) na sequência desejada, mas acabou sendo muito mais simples, o próprio pandoc é perfeitamente capaz de trabalhar com a lista de arquivos. Isso também nos permitiu resolver parcialmente o problema de que precisamos de vários documentos nos quais o conteúdo pode se cruzar. Por exemplo, geramos três documentos e todos os três contêm uma breve seção de descrição. Simplesmente listamos esse arquivo na lista de pandoc para todos os documentos.
Aplicamos um princípio semelhante às páginas de rosto em que o título do documento está, e assim por diante. Acabamos de criar arquivos com cabeçalhos para cada documento e incluí-los como os primeiros arquivos na lista de fontes do pandoc.
Como você provavelmente adivinhou, isso (uma lista de arquivos diferentes) resolve o problema com o multilinguismo, apenas especificamos os arquivos com o idioma desejado.
Vamos falar um pouco mais de russo. Ao gerar pdf, o pandoc usa o látex como back-end para renderização, verificador ortográfico etc. Por padrão, cirílico não é exibido e um erro sobre um caractere desconhecido é exibido. Isso é resolvido de maneira muito simples, basta especificar "babel russian".
--- ... header-includes: - \usepackage[russian]{babel} ---
Deve-se notar que é mais correto indicar
--- ... header-includes: - \usepackage[russian, english]{babel} ---
E use comandos de látex no texto
\selectlanguage{russian} \foreignlanguage{english}{ English text }
Ou
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
Mas como queríamos manter uma remarcação “limpa” para possível transferência para o wiki, e a diretiva babel era suficiente para nossos propósitos, decidimos não complicá-la e deixá-la como está.
Obviamente, não queríamos ter documentos formatados, mas pelo menos parecendo uniformes. E aqui o látex nos ajudou novamente. O fato é que, como o pandoc usa o látex, você pode especificar modelos de látex para ele. Isso é feito simplesmente com a opção --template
pandoc --template=embox_pandoc.latex ...
Depois de compilar um modelo e especificá-lo ao gerar todos os documentos, você obtém os documentos em um estilo mais ou menos uniforme. "Mais ou menos" - porque existem vários problemas que não conseguimos resolver. Por exemplo, a formação de um único bloco de código. Na redução, é possível especificar um único bloco de código para que não seja formatado e o realce de sintaxe esteja ativado. Mas conseguimos fazer apenas blocos de uma linha. Isso acabou depois de analisar o código de látex gerado.
Ou seja, houve casos em que o mesmo bloco foi colocado em documentos diferentes de maneira um pouco diferente.
Outro ponto relacionado ao alfabeto cirílico, ou seja, o uso da língua russa. Como mencionado acima, para usar o idioma russo, bastava especificar babel russo no cabeçalho. Mas encontramos algumas esquisitices, por exemplo, não havia realce em negrito e outras esquisitices de formatação. Inicialmente, pecamos no fato de que o russo é especificado em maiúsculas e não em um modelo. Eles começaram a estudar o problema. Acontece que, de uma maneira boa, você precisa não apenas usar
\usepackage[russian, english]{babel}
mas também
definir fontes \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
Mas, mesmo tendo feito isso, não foi possível corrigir a situação. Verificou-se que nem todos os conjuntos de fontes contêm todas as opções de renderização, em particular as nossas não contêm negrito, itálico e outros formatos. Como não havia uma solução simples para o problema, pensamos e adiamos o problema para tempos melhores. Bem, como queríamos usar uma marcação limpa (ou seja, sem especificar comandos de látex), criamos um modelo comum para os dois idiomas, e a indicação sobre o idioma russo foi colocada no cabeçalho.
Apenas algumas palavras que direi sobre a interface do próprio aplicativo. Como, como eu disse, os aplicativos de console são pessoalmente muito familiares para nós e são facilmente empacotados em scripts. Na verdade, a interface é simples, é claro que você pode definir muitas opções, mas, para nossos propósitos, basta especificar um modelo, uma lista de arquivos de entrada e um arquivo de saída.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
Na Internet, você pode descobrir que, para gerar pdf (ou outro formato de saída), é necessário um tipo de processador usando a opção --pdf-engine = xelatex, mas, por padrão, é usado se o arquivo de saída tiver a extensão pdf. Portanto, também não precisamos disso.
Empacotamos os scripts para montar a documentação em um Makefile, para que se tornasse bastante familiar. E agora, para obter a documentação, você pode definir o ambiente necessário, basta ligar
make [en][ru]
Em conclusão, algumas palavras sobre o sistema de controle de versão. O princípio é não complicar (manter a simplicidade), tentamos aderir a tudo. E como a solução mais simples era usar um repositório separado no github, então o
fizemos . Esperamos que o uso do github melhore o feedback do usuário. Afinal, como você sabe no github, existem questões nas quais você pode discutir deficiências e oferecer suas idéias e orientações.
Este processo foi lançado recentemente, a pedido de muitos trabalhadores! Conseguimos fazer as versões em
inglês e
russo do "início rápido", bem como a
primeira versão do manual do usuário em russo . O processo em si parecia mais conveniente para nós, e é por isso que o compartilhamos com o público.