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:
- Open Collective
- Redator técnico:
- Anna e só
- Nome do projeto:
- Melhorar a documentação geral de ajuda
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Primeiras impressões É comum encontrar páginas de documentação contendo 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 de instruções, enquanto Add Fiscal Host incorpora mídia de apoio.
Nas páginas que naveguei, nenhuma mídia é descrita com o atributo de texto alternativo. A falta de descrições de imagens dificulta o entendimento completo da documentação para aqueles que usam leitores de tela e pessoas com conexões de Internet mais lentas, onde qualquer mídia pode não ser carregada.
Algumas seções da documentação mesclam perguntas frequentes e instruções diretas para navegar na interface do usuário, como Alterar host fiscal. Como não há sumário na interface de documentação, um usuário que esteja ciente das consequências de uma alteração nos registros de registro e apenas queira instruções objetivas pode considerar a documentação detalhada e muito tangencial.
Embora a linguagem da documentação técnica seja bastante consistente, o Guia de estilo, disponível publicamente, não explica muito bem como a documentação deve ser escrita. Como a página Contribuições menciona as contribuições para a documentação técnica, tanto o Open Collective quanto os possíveis colaboradores se beneficiariam de diretrizes mais abrangentes.
Proposta Proponho uma revisão das páginas de ajuda dos 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 promovendo ciclos de feedback contínuo de duração variável.
Período de vínculo com a comunidade (1o de agosto a 1o de setembro de 2019): conhecer a comunidade do Open Collective! Entrevistar membros ativos de projetos iniciais e de destaque, fazendo perguntas sobre o estado atual da documentação (Relatório no 1). Anote todos os sistemas internos usados para rastrear consultas e problemas e o processo para documentá-los no Open Collective Docs (Relatório no 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 interação. Nosso plano está pronto? Há algo nele que precise mudar? (Relatório no 4)
9 a 20 de setembro: desenvolvimento da prova de conceito com o capítulo menos preenchido da documentação. Rascunho de um Guia de estilo público (Relatório no 5).
23 a 25 de setembro: envio da prova de conceito para avaliação (grupo fechado).
26 a 27 de setembro: nossa prova de conceito precisa de ajustes antes de ser publicada? Precisamos de mais tempo? Ajuste de acordo. (Relatório no 6)
30 de setembro a 9 de outubro: a prova de conceito é publicada. Segundo ciclo de feedback (grupo público).
10 a 15 de outubro: avaliação final da prova de conceito e ciclo de ajuste. (Relatório no 7)
16 a 20 de outubro: um pequeno intervalo nas atividades [1].
21 de outubro a 23 de novembro: o Guia de estilo público é final (relatório no 8). Aplicação de todas as instruções presentes no Guia de estilo a todas as páginas de documentação do usuário (Relatório no 9). Relatório que avalia todas as atividades realizadas e mais recomendações para a comunidade (Relatório no 10).
A duração do projeto pode ser estendida mediante solicitação.
[1]: Viagem planejada antes do meu aplicativo na temporada de documentos.
Resultados - Dez relatórios públicos sobre as atividades realizadas - Um guia de estilo público que pode ser usado por colaboradores externos e do Open Collective - Páginas de documentação do usuário renovadas