Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- HPX
- Escritor técnico:
- aprendo
- Nombre del proyecto:
- Edita y optimiza 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 de HPX existente. Mi propuesta es para un proyecto de plazo estándar (tres meses) que se centra en la revisión de dos capítulos del manual del grupo STE||AR: ""Sistema de compilación y lanzamiento de HPX" (1) y "Configuración de aplicaciones HPX"" (2).
El capítulo sobre "HPX Build System and Launching" tiene varios errores gramaticales y también contiene lenguaje confuso y mayúsculas incoherentes 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 "Cómo configurar aplicaciones HPX" también contiene algunos errores gramaticales que deben abordarse, mi principal preocupación respecto de este capítulo es su facilidad de uso. El capítulo tiene tres problemas de diseño principales que pienso abordar:
Algunos encabezados están ocultos en el texto, lo que dificulta la lectura rápida del capítulo. Actualmente, los usuarios tendrían que leer el manual detenidamente 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, especialmente si ya leyeron el contenido antes. En cambio, pienso asegurarme de que cada tabla tenga un encabezado claro y distinto, que se pueda ver fácilmente si un usuario se desplaza por el texto.
Al enumerar varias propiedades bajo un encabezado particular, las propiedades no siguen un orden lógico. Si bien las propiedades se agrupan bajo un tema común, no hay subagrupaciones, lo que hace que la información se sienta dispersa. Por ejemplo, un usuario puede encontrar varias propiedades que se ocupan de la localidad, algunas que se ocupan de otro tema y otras que se ocupan de la localidad. Esta falta de estructura interna bajo 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 más claramente la información similar bajo cada encabezado.
Los usuarios se ven obligados a navegar entre 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 poco claro como “este paso se preforma 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 alternando entre secciones o documentos.
Si completo estas secciones antes de que termine el cronograma estándar, también me gustaría borrar la página “¿Por qué HPX?” (3) en la documentación del usuario del grupo STE||AR. Esta página incluye contenido introductorio repetitivo, que espero consolidar y contiene inconsistencias en el uso de mayúsculas (especialmente la jerga) y la voz, que le dan una sensación desunificada. Mi objetivo es crear una introducción más unificada y coherente al trabajo del grupo STE||AR.