Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Linux Foundation
- Redator técnico:
- boro
- Nome do projeto:
- Reformular a documentação de hospedagem e geração e reestruturar as páginas iniciais e os guias para desenvolvedores.
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Resumo :
A documentação é projetada para ajudar os usuários finais e desenvolvedores a usar um produto ou serviço. Uma boa documentação é muito importante porque fornece aos usuários um meio para aprender como usar um software, seus recursos, dicas, truques e também resolver problemas comuns encontrados ao usar o software. 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 forma eficaz e eficiente. As documentações podem desempenhar um papel essencial para garantir o sucesso de um produto, porque uma boa comunicação é e sempre será o centro de qualquer negócio ou produto, e uma ótima documentação apenas usa essa comunicação e a coloca em uma estrutura gerenciável que todos podem acessar para o sucesso.
Todo site de documentação precisa de um bom pipeline de criação e hospedagem de fluxo de trabalho. Em uma organização como a AGL, com várias versões e muita documentação, os arquivos de documentação (marcações) estão espalhados por vários repositórios, tornando a tarefa de manter e atualizar incrivelmente complexa e demorada.
Situação atual :
- O site de documentos do AGL é baseado em uma coleção de arquivos markdown buscados em vários repositórios.
- As páginas de documentos estão atualmente hospedadas em fontes individuais como markdown usando o mecanismo do projeto Cordova.
- Isso leva à 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 do Jekyll.
- Ferramentas de documentos [https://github.com/automotive-grade-linux/docs-tools] : contém ferramentas para gerar automaticamente um site técnico com arquivos Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : fonte (marcações [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) para documentos gerais e 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 de markdown de acordo com o fetch_files.yaml localizado no docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- O fluxo de trabalho atual de geração de site de documentação do agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOTIPtdPf42EIfpidUJ0U/view?usp=sharing]
- O section_version.params contém os links para todos os arquivos YAML do livro. Ele continua a buscar 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 todo o URL para seus arquivos de marcação do repositório remoto.
- Assim que todos os arquivos Markdown são buscados, as ferramentas processam para gerar o site do documento AGL em 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 é fácil de usar nem de desenvolver para o desenvolvedor, especialmente para novos colaboradores. Esse pipeline de fluxo de trabalho (de criação e hospedagem) pode ser simplificado e otimizado muito mais para que os desenvolvedores se concentrem na documentação em vez de manter o fluxo de trabalho de geração e implantação de documentação.