Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- HPX
- Redactor técnico:
- rstobaugh
- Nombre del proyecto:
- Editar y optimizar la documentación existente de HPX
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Mi propuesta es editar y optimizar el contenido de la documentación existente de HPX. Mi propuesta es un proyecto de período estándar (tres meses) que se enfoque en revisar dos capítulos del manual del grupo STE||AR: ""Sistema de compilación y lanzamiento de HPX"" (1) y ""Configuración de aplicaciones de HPX"" (2).
El capítulo sobre ""HPX Build System and Launching"" tiene varios errores gramaticales y también contiene lenguaje confuso y mayúsculas inconsistentes de términos como "CMake". Además, contiene información repetida, que planeo reorganizar, consolidar y recortar según sea necesario. Si bien el capítulo sobre ""Configuración de aplicaciones de HPX"" también contiene algunos errores gramaticales que deben corregirse, mi principal preocupación con respecto a este capítulo es su facilidad de uso. El capítulo tiene tres problemas de diseño principales que planeo abordar:
Algunos encabezados están ocultos en el texto, lo que dificulta la lectura rápida del capítulo. Actualmente, un usuario tendría que leer el manual con cuidado para comprender el propósito de cada tabla. Esta no es la forma en que la mayoría de los usuarios interactúan con los manuales de instrucciones, en especial si ya leyeron el contenido antes. En cambio, quiero asegurarme de que cada tabla tenga un encabezado claro y distinto, que se pueda ver fácilmente si el usuario se desplaza por el texto.
Cuando se enumeran varias propiedades en un encabezado en particular, estas no siguen un orden lógico. Si bien las propiedades se agrupan en función de un tema común, no hay subgrupos, lo que hace que la información parezca dispersa. Por ejemplo, un usuario puede encontrar varias propiedades que se relacionan con la localidad, algunas que se relacionan con otro tema y, luego, otra que se relaciona con la localidad. Esta falta de estructura interna en los encabezados dificulta la ubicación de toda la información sobre un subtema específico. Por lo tanto, pienso reorganizar varios de los gráficos para agrupar de manera más clara la información similar bajo cada encabezado.
Los usuarios se ven obligados a navegar de un lado a otro entre las secciones (o abrir el manual en dos pestañas separadas) para comprender completamente ciertas instrucciones. Hay puntos en los que el capítulo dirige al usuario a una sola oración dentro de una sección anterior de una manera que obliga al lector a desplazarse hacia arriba o seguir un hipervínculo para comprender la instrucción exacta, ya que el manual usa un lenguaje vago, como “este paso se realiza después del paso 11” en la sección anterior. Si bien este método elimina la repetición, dificulta la comprensión de las instrucciones, ya que son tareas que deben realizarse en un orden específico. En cambio, propongo incluir una redacción más específica para que los usuarios no tengan que interrumpir su proceso de lectura al cambiar entre secciones o documentos.
Si completo estas secciones antes de que finalice el cronograma estándar, también me gustaría ordenar la página “¿Por qué HPX?” (3) en la documentación para el usuario del grupo STE||AR. Esta página contiene contenido introductorio repetitivo, que espero consolidar, y tiene inconsistencias en la mayúscula (en particular, en el lenguaje técnico) y en el tono, lo que le da una sensación de desunión. Mi objetivo sería crear una introducción más unificada y coherente al trabajo del grupo STE||AR.