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:
- HPX (em inglês)
- Redator técnico:
- rstobaugh
- Nome do projeto:
- Editar e simplificar a documentação do HPX
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Minha proposta é editar e simplificar o conteúdo da documentação atual do HPX. Minha proposta é para um projeto de prazo padrão (de três meses) que se concentra na revisão de dois capítulos do manual do grupo STE||AR: ""HPX Build System and Launching"" (1) e ""Setup HPX Applications"" (2).
O capítulo ""HPX Build System and Launching"" tem vários erros gramaticais e também apresenta linguagem confusa e letras maiúsculas inconsistentes em termos como "CMake". Além disso, ele contém informações repetidas, que pretendo reorganizar, consolidar e cortar conforme necessário. Embora o capítulo sobre ""Como configurar aplicativos HPX"" também contenha alguns erros gramaticais que precisam ser resolvidos, minha principal preocupação neste capítulo é a facilidade de uso. O capítulo tem três problemas de design principais que pretendo abordar:
Alguns títulos estão escondidos no texto, dificultando a leitura do capítulo. Atualmente, um usuário precisaria ler o manual com atenção para entender a finalidade de cada tabela. Não é assim que a maioria dos usuários interage com os manuais de instruções, principalmente se já tiverem lido o conteúdo antes. Em vez disso, pretendo garantir que cada tabela tenha um cabeçalho claro e distinto, que possa ser facilmente visto se um usuário rolar o texto.
Ao listar várias propriedades sob um título específico, elas não seguem uma ordem lógica. Embora as propriedades sejam agrupadas em um tema comum, não há subagrupamentos, o que faz com que as informações pareçam dispersas. Por exemplo, um usuário pode encontrar várias propriedades que lidam com a localidade, algumas que estão relacionadas a outro assunto e, em seguida, outra que lida com a localidade. Essa falta de estrutura interna sob os títulos dificulta a localização de todas as informações sobre um subtópico específico. Portanto, pretendo reorganizar vários gráficos para agrupar mais claramente informações semelhantes em cada título.
Os usuários são forçados a navegar entre as seções (ou a abrir o manual em duas guias separadas) para entender completamente determinadas instruções. Há pontos em que o capítulo direciona o usuário a uma única frase de uma seção anterior de forma que obrigue o leitor a rolar para cima ou seguir um hiperlink para entender a instrução exata. O manual usa linguagem vaga, como "esta etapa é pré-formada após a etapa 11" na seção anterior. Embora esse método elimine a repetição, dificulta o entendimento das instruções, pois essas são tarefas que precisam ser pré-formadas em uma ordem específica. Em vez disso, proponho a inclusão de um texto mais específico para que os usuários não precisem interromper seu processo de leitura alternando entre seções ou documentos.
Se eu concluir essas seções antes do fim do cronograma padrão, também gostaria de limpar a página “Why HPX?” (3) na documentação do usuário do grupo STE||AR. Esta página apresenta conteúdo introdutório repetitivo, que esperamos consolidar e contém inconsistências na capitalização (principalmente com jargões) e na voz, o que dá a ela uma sensação desunal. Minha meta é criar uma apresentação mais unificada e consistente com o trabalho do grupo STE||AR.