Projet HPX

Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.

Résumé du projet

Organisation Open Source:
HPX
Rédacteur technique:
rstobaugh
Nom du projet:
Modifier et simplifier la documentation HPX existante
Durée du projet:
Durée standard (trois mois)

Project description

Ma proposition consiste à modifier et à simplifier le contenu de la documentation HPX existante. Je propose un projet de durée standard (trois mois) axé sur la révision de deux chapitres du manuel du groupe STE||AR: ""HPX Build System and Launching"" (1) et ""Configuring HPX Applications"" (2).

Le chapitre sur le ""système de compilation et de lancement HPX"" contient plusieurs erreurs grammaticales, ainsi qu'un langage confus et une capitalisation incohérente de termes tels que "CMake". De plus, il contient des informations répétées, que je prévois de réorganiser, de regrouper et d'élaguer si nécessaire. Bien que le chapitre ""Configuring HPX Applications"" contienne également quelques erreurs grammaticales qui doivent être corrigées, mon principal souci concernant ce chapitre est sa facilité d'utilisation. Le chapitre comporte trois problèmes de conception majeurs que je prévois de résoudre:

  1. Certains titres sont enfouis dans le texte, ce qui rend difficile de parcourir le chapitre. Actuellement, un utilisateur doit lire attentivement le manuel pour comprendre l'objectif de chaque tableau. Ce n'est pas ainsi que la plupart des utilisateurs interagissent avec les manuels d'instructions, en particulier s'ils ont déjà lu le contenu auparavant. Je prévois plutôt de m'assurer que chaque tableau comporte un titre clair et distinct, qui peut être facilement vu si un utilisateur fait défiler le texte.

  2. Lorsque vous répertoriez différentes propriétés sous un en-tête particulier, celles-ci ne suivent pas un ordre logique. Les établissements sont regroupés par thème commun, mais il n'y a pas de sous-groupes, ce qui donne l'impression que les informations sont dispersées. Par exemple, un utilisateur peut rencontrer plusieurs propriétés qui traitent de la localité, quelques-unes qui traitent d'un autre sujet, puis une autre qui traite de la localité. Ce manque de structure interne sous les en-têtes rend plus difficile la localisation de toutes les informations sur un sous-sujet spécifique. Par conséquent, je prévois de réorganiser plusieurs graphiques afin de regrouper plus clairement les informations similaires sous chaque titre.

  3. Les utilisateurs sont obligés de passer d'une section à l'autre (ou d'ouvrir le manuel dans deux onglets distincts) pour comprendre pleinement certaines instructions. À certains endroits, le chapitre redirige l'utilisateur vers une seule phrase d'une section précédente de manière à le forcer à faire défiler la page vers le haut ou à suivre un lien hypertexte pour comprendre l'instruction exacte, car le manuel utilise un langage vague tel que "cette étape est effectuée après l'étape 11" dans la section précédente. Bien que cette méthode élimine les répétitions, elle rend les instructions plus difficiles à comprendre, car il s'agit de tâches qui doivent être effectuées dans un ordre spécifique. À la place, je propose d'inclure une formulation plus spécifique afin que les utilisateurs n'aient pas à interrompre leur processus de lecture en passant d'une section ou d'un document à l'autre.

Si je termine ces sections avant la fin du calendrier standard, je voudrais également nettoyer la page "Pourquoi HPX ?" (3) dans la documentation utilisateur du groupe STE||AR. Cette page contient du contenu introductif répétitif, que j'espère consolider. Elle présente également des incohérences dans la capitalisation (en particulier du jargon) et dans le ton, ce qui lui donne un aspect désuni. Mon objectif est de créer une introduction plus unifiée et cohérente au travail du groupe STE||AR.

  1. https://stellar-group.github.io/hpx/docs/sphinx/latest/html/manual/building_hpx.html
  2. https://stellar-group.github.io/hpx/docs/sphinx/latest/html/manual/launching_and_configuring_hpx_applications.html
  3. https://stellar-group.github.io/hpx/docs/sphinx/latest/html/why_hpx.html