Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- HPX
- Rédacteur technique:
- entrer dans le camp
- Nom du projet:
- Modifier et simplifier la documentation HPX existante
- Durée du projet:
- Durée standard (3 mois)
Project description
Je propose de modifier et de simplifier le contenu de la documentation HPX existante. Ma proposition porte sur un projet d'une durée standard (trois mois) portant sur la révision de deux chapitres du manuel du groupe STE||AR : "HPX Build System and Launching" (1) et "Configuring HPX Applications" (2) : "HPX Build System and Launching" (1) et "Configuring HPX Applications" (2).
Le chapitre sur « Système de compilation et lancement HPX » comporte plusieurs erreurs grammaticales et contient également un langage confus et une casse incohérente de termes comme « CMake ». De plus, il contient des informations répétées que je prévois de réorganiser, de regrouper et de supprimer si nécessaire. Bien que le chapitre sur la configuration des applications HPX comporte également quelques erreurs grammaticales à corriger, ma principale préoccupation est la convivialité de ce chapitre. Ce chapitre comporte trois grands problèmes de conception que je prévois de traiter:
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 la fonction de chaque tableau. Ce n'est pas ainsi que la plupart des utilisateurs interagissent avec les manuels d'instructions, surtout s'ils ont déjà lu le contenu auparavant. Au lieu de cela, je prévois de m'assurer que chaque tableau a un en-tête clair et distinct, qui est facilement visible si l'utilisateur fait défiler le texte.
Lorsque vous répertoriez différentes propriétés sous un titre particulier, elles ne suivent pas un ordre logique. Bien que les propriétés soient regroupées sous un thème commun, il n'y a pas de sous-groupes, ce qui donne l'impression que les informations sont dispersées. Par exemple, un utilisateur peut voir plusieurs propriétés portant sur la localité, d'autres portant sur un autre sujet, puis d'autres portant sur 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.
Les utilisateurs sont obligés de passer d'une section à l'autre (ou d'ouvrir le manuel dans deux onglets distincts) pour bien comprendre certaines instructions. Il y a des moments où le chapitre dirige l'utilisateur vers une seule phrase d'une section précédente, d'une manière qui oblige le lecteur à faire défiler vers le haut ou à suivre un lien hypertexte pour comprendre l'instruction exacte, car le manuel utilise un langage vague comme « cette étape est préformée après l'étape 11 » dans la section précédente. Bien que cette méthode élimine les répétitions, elle rend plus difficile la compréhension des instructions, car ce sont des tâches qui doivent être effectuées dans un ordre spécifique. Je propose plutôt d'inclure des formulations plus spécifiques 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 remplis ces sections avant la fin de la chronologie standard, j’aimerais également nettoyer la page « Pourquoi HPX ? » (3) dans la documentation utilisateur du groupe STE||AR. Cette page présente des contenus d'introduction répétitifs, que nous espérons regrouper et qui comporte des incohérences au niveau des majuscules (en particulier du jargon) et du ton, qui donnent une impression de désunification. Mon objectif est de créer une introduction plus unifiée et cohérente au travail du groupe STE||AR.