Abrir projeto do Collective

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