Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- The Linux Foundation
- Redator técnico:
- boro
- Nome do projeto:
- Retrabalhar a hospedagem e geração de documentação e reestruturar as páginas de início e os guias para desenvolvedores.
- Duração do projeto:
- Duração padrão (três meses)
Project description
Abstrata :
A documentação é projetada para ajudar os usuários finais e os desenvolvedores a usar um produto ou serviço. Uma boa documentação é muito importante porque oferece aos usuários uma forma de aprender a usar um software, seus recursos, dicas, truques e também resolver problemas comuns encontrados ao usar o software. Ela também reduz o custo do suporte e faz parte da identidade corporativa e de código aberto do produto : uma boa documentação é um sinal de integridade do produto e da equipe de desenvolvimento.
Sem uma boa documentação, o usuário pode não saber como fazer as coisas acima de maneira eficaz e eficiente. A documentação pode ter um papel fundamental para garantir o sucesso de um produto, porque uma boa comunicação é e sempre será o centro de qualquer negócio ou produto. Uma boa documentação apenas leva essa comunicação para um framework gerenciável que todos podem acessar para ter sucesso.
Todo site de documentação precisa de um bom pipeline de fluxo de trabalho de criação e hospedagem. Em uma organização como a AGL, com várias versões e muita documentação elaborada, os arquivos de documentação (markdowns) são distribuídos por vários repositórios, o que torna a tarefa de manutenção e atualização deles incrivelmente complexa e demorada.
Estado atual :
- O site de documentos do AGL é baseado em uma coleção de arquivos Markdown buscados de vários repositórios.
- No momento, as páginas de documentos são hospedadas nas fontes individuais como markdown usando o mecanismo do projeto cordova.
- Isso leva a uma configuração de quatro repositórios para o processo de hospedagem e criação de documentação :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : contém o modelo de site do Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : contém ferramentas para gerar automaticamente um site técnico a partir de arquivos Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : fonte (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) para documentos gerais, guias.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : repositório GitHub Pages implantado para o site de documentação [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Uma ferramenta (script) disponível em docs-tools [https://github.com/automotive-grade-linux/docs-tools] coleta e gera modelos de todos os arquivos Markdown de acordo com o fetched_files.yml localizado em docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- O fluxo de trabalho atual da geração de site de documentação da Agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOdashboardtdPf42EIfpidUJ0U/view?usp=sharing]
- O arquivo section_version.yml contém os links para todos os arquivos yaml do livro e extrai todos os arquivos yaml do livro dos repositórios remotos para o docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Os arquivos yaml de livros contêm todos os URLs para os arquivos de marcação do repositório remoto.
- Assim que todos os arquivos Markdown forem buscados, as ferramentas vão processar a geração do site de documentos do AGL no docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], que será implantado.
- O processo atual de manutenção do pipeline não é fácil de usar e nem de desenvolver, especialmente para novos colaboradores. Esse pipeline de fluxo de trabalho (de criação e hospedagem) pode ser simplificado e simplificado para que os desenvolvedores se concentrem na parte da documentação, em vez de manter a geração de documentação e o fluxo de implantação.