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:
- Open Collective (em inglês)
- Redator técnico:
- Anna e só
- Nome do projeto:
- Melhorar a documentação de ajuda geral
- Duração do projeto:
- Duração padrão (três meses)
Project description
Primeiras impressões É comum encontrar páginas de documentação com instruções sem mídia de apoio (vídeos, GIFs, imagens), enquanto outras seções do mesmo capítulo têm entradas mais completas. Por exemplo, Edit Collective é composto apenas por instruções, enquanto Add Fiscal Host incorpora mídia de apoio.
Nas páginas que naveguei, nenhuma mídia é descrita usando o atributo de texto alternativo. A falta de descrições de imagens dificulta a compreensão completa da documentação para quem usa leitores de tela e pessoas em conexões de Internet mais lentas, em que pode ocorrer falha no carregamento de qualquer mídia.
Algumas seções da documentação mesclam perguntas frequentes e instruções diretas para navegar na interface do usuário, como Mudar o host fiscal. Como não há um sumário na interface da documentação, um usuário que conhece as consequências de uma mudança nos registros de registro e só quer instruções objetivas pode achar a documentação prolixa e muito indireta.
Embora a linguagem da documentação técnica seja bastante consistente, o guia de estilo disponível publicamente não documenta o suficiente sobre como a documentação deve ser escrita. Como a página Contribuições menciona contribuições à documentação técnica, tanto o Open Collective quanto possíveis colaboradores se beneficiariam de diretrizes mais abrangentes.
Proposta Proponho uma revisão das páginas de ajuda para usuários, repensando a apresentação e a estrutura atual.
Metodologia e cronograma Quero melhorar a documentação do Open Collective trabalhando com a comunidade para promover ciclos de feedback contínuo de duração variável.
Período de integração da comunidade (1º de agosto a 1º de setembro de 2019): conheça a comunidade do Open Collective! Entrevistar membros ativos de projetos importantes e iniciais, fazendo perguntas sobre o estado atual da documentação (Relatório 1). Anote todos os sistemas internos usados para rastrear consultas e problemas e o processo para documentá-los nos documentos do Open Collective (relatório 2). Avaliação de problemas latentes na versão atual da documentação e preparação de um plano para resolvê-los (Relatório no 3).
2 a 6 de setembro: primeiro ciclo de feedback e ajuste, considerando todos os comentários e sugestões feitos pela comunidade durante o período de integração. Nosso plano está pronto? Há algo que precisa mudar? (Relatório no 4)
9 a 20 de setembro: desenvolvimento de prova de conceito com o capítulo menos preenchido da documentação. Rascunho de um guia de estilo público (relatório 5).
23 a 25 de setembro: envio da prova de conceito para avaliação (grupo fechado).
26 e 27 de setembro: nossa prova de conceito precisa de ajustes antes de ser lançada? Precisamos de mais tempo? Faça os ajustes necessários. (Relatório 6)
30 de setembro a 9 de outubro: a prova de conceito é lançada. Segundo ciclo de feedback (grupo público).
10 a 15 de outubro: ciclo final de avaliação e ajuste da prova de conceito. (Relatório 7)
16 a 20 de outubro: pequena pausa nas atividades [1].
21 de outubro a 23 de novembro: o Public Style Guide é finalizado (Relatório 8). Aplicação de todas as instruções presentes no guia de estilo a todas as páginas da documentação do usuário (relatório 9). Relatório que avalia todas as atividades realizadas e outras recomendações para a comunidade (relatório no 10).
A duração do projeto pode ser estendida mediante solicitação.
[1]: Viagem planejada antes da minha inscrição na Temporada de documentos.
Produtos - Dez relatórios públicos sobre as atividades realizadas - Um guia de estilo público que o Open Collective e colaboradores externos podem usar - Páginas de documentação do usuário reformuladas