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:
- HPX
- Redator técnico:
- rstobaugh
- Nome do projeto:
- Editar e simplificar a documentação existente do HPX
- Duração do projeto:
- Duração padrão (três meses)
Project description
Minha proposta é editar e simplificar o conteúdo da documentação HPX existente. Minha proposta é para um projeto de prazo padrão (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 ""Configuring HPX Applications"" (2).
O capítulo "Sistema de criação e lançamento HPX" tem vários erros gramaticais, além de conter linguagem confusa e uso inconsistente de 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 "Como configurar aplicativos HPX" também contenha alguns erros gramaticais que precisam ser abordados, minha principal preocupação para este capítulo é sua facilidade de uso. O capítulo tem três problemas principais de design que pretendo abordar:
Alguns títulos estão escondidos no texto, o que dificulta a leitura do capítulo. Atualmente, um usuário precisa ler o manual com atenção para entender a finalidade de cada tabela. Essa não é a forma como a maioria dos usuários interage com manuais de instruções, especialmente se eles já leram 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 pelo texto.
Ao listar várias propriedades sob um título específico, as propriedades não seguem uma ordem lógica. Embora as propriedades sejam agrupadas sob um tema comum, não há subgrupos, o que faz com que as informações pareçam dispersas. Por exemplo, um usuário pode encontrar várias propriedades que tratam da localidade, algumas que tratam de outro assunto e outra que trata da localidade. Essa falta de estrutura interna nos títulos dificulta a localização de todas as informações sobre um determinado subtópico. Portanto, pretendo reorganizar vários gráficos para agrupar informações semelhantes de forma mais clara em cada título.
Os usuários são forçados a navegar entre as seções (ou abrir o manual em duas guias separadas) para entender completamente algumas instruções. Há pontos em que o capítulo direciona o usuário a uma única frase em uma seção anterior de uma maneira que força o leitor a rolar para cima ou seguir um hiperlink para entender a instrução exata, já que o manual usa linguagem vaga, como "esta etapa é realizada após a etapa 11" na seção anterior. Embora esse método elimine a repetição, ele dificulta a compreensão das instruções, já que são tarefas que precisam ser realizadas em uma ordem específica. Em vez disso, proponho incluir uma linguagem mais específica para que os usuários não precisem interromper o processo de leitura alternando entre seções ou documentos.
Se eu concluir essas seções antes do término do cronograma padrão, também gostaria de limpar a página "Por que 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 de letras maiúsculas (principalmente de jargão) e de voz, o que dá uma ideia desunificada. Meu objetivo é criar uma introdução mais unificada e consistente ao trabalho do grupo STE||AR.