Esta página contém os detalhes de um projeto de redação técnica aceito para o Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- The Linux Foundation
- Redator técnico:
- boron
- Nome do projeto:
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- Duração do projeto:
- Padrão (3 meses)
Descrição do projeto
Abstrata :
Uma documentação é projetada para ajudar usuários finais e desenvolvedores a usar um produto ou serviço. Uma boa documentação é muito importante porque oferece aos usuários uma maneira de aprender a usar um software, seus recursos, dicas e truques, além de resolver problemas comuns encontrados ao usar o software. Ela também reduz o custo de 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, um usuário pode não saber como fazer as coisas acima de maneira eficaz e eficiente. As documentações podem desempenhar um papel fundamental para garantir o sucesso de um produto, porque uma ótima comunicação é e sempre será o centro de qualquer empresa ou produto, e uma ótima documentação apenas pega essa comunicação e a coloca em uma estrutura 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 em vários repositórios, tornando a tarefa de manutenção e atualização incrivelmente complexa e demorada.
Estado atual :
- O site de documentação da AGL é baseado em uma coleção de arquivos markdown extraídos de vários repositórios.
- As páginas de documentação estã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 criação e hospedagem da documentação :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : contém o modelo de site 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 de páginas do GitHub 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] cuida da coleta e do modelo 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 do site de documentação da AGL : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- O section_version.yml contém os links para todos os arquivos yaml do livro. Ele extrai todos os arquivos yaml do livro de repositórios remotos para o docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Os arquivos yaml do livro contêm todos os URLs dos arquivos markdown do repositório remoto.
- Assim que todos os arquivos markdown são extraídos, as ferramentas processam para gerar o site de documentação da AGL no docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], que é implantado de maneira correspondente.
- O processo atual de manutenção do pipeline não é amigável para usuários e desenvolvedores, especialmente para novos colaboradores. Esse pipeline de fluxo de trabalho (de criação e hospedagem) pode ser simplificado e otimizado para que os desenvolvedores se concentrem na parte de documentação em vez de manter o fluxo de trabalho de geração e implantação de documentação.