Projet SciPy

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:

SciPy

Rédacteur technique:

mkg33

Nom du projet:

Documentation axée sur l'utilisateur et restructuration complète

Durée du projet:

Durée standard (3 mois)

Project description

Motivation:

J'ai l'intention de travailler sur le refactoring de la documentation existante afin qu'elle soit facilement accessible aux utilisateurs ayant des besoins différents. Il va sans dire qu'un chercheur est le plus susceptible d'être intéressé par des fonctionnalités avancées et subtiles, tandis qu'un utilisateur sans expertise préalable appréciera les guides et les diagrammes détaillés.

Je souhaite poursuivre ce projet pour des raisons personnelles et professionnelles: d'abord, je voudrais contribuer de manière significative à SciPy, car mes propres recherches en ont grandement bénéficié. Ensuite, je rencontre trop souvent une documentation insuffisante (ou inexistante) dans d'autres logiciels et je me demande toujours à quel point les utilisateurs pourraient apprendre à utiliser le code plus rapidement (ou du tout) s'ils avaient reçu un guide complet.

Objectifs :

Je souhaite améliorer la documentation SciPy existante, tant au niveau du contenu que de la présentation. La caractéristique la plus importante de mon approche de ce problème est le déploiement et l'analyse de l'enquête auprès des utilisateurs, c'est-à-dire une enquête concise menée en ligne permettant à divers utilisateurs d'exprimer leurs besoins concernant la documentation. Je suis convaincue que leurs opinions doivent être la source d'inspiration (comment pouvons-nous créer une documentation plus conviviale ?).

En ce qui concerne la réalisation du projet en lui-même, la première phase consistera à concevoir et à analyser l'enquête auprès des utilisateurs, ainsi qu'à s'attaquer à plusieurs problèmes stylistiques que j'ai remarqués dans la documentation actuelle. Par exemple, manque de cohérence (par exemple, tableaux à deux dimensions qui se produisent à côté de tableaux à deux dimensions), phrases alambiquées qui devraient être réécrites ou absence d'ordre alphabétique sur certaines sous-pages. La deuxième phase sera axée sur l'introduction de guides graphiques contenant des liens hypertextes vers les sujets pertinents (en fonction des résultats de l'enquête et d'autres demandes de la communauté). À terme, je souhaite obtenir une documentation satisfaisante adaptée à différents types d'utilisateurs. De plus, je vais essayer de rendre les tutoriels plus cohérents, tant sur le plan linguistique que structurel. Enfin, je vais rédiger de nouveaux tutoriels (en fonction des besoins actuels de la communauté).

Enquête auprès des utilisateurs:

Pour l'enquête auprès des utilisateurs, je propose d'utiliser Google Forms pour plusieurs raisons. Tout d'abord, Google Forms est sans frais et offre des fonctionnalités illimitées (en termes de nombre de personnes interrogées, de questions, etc.). Il présente une forme visuelle attrayante, les options d'enquête les plus utiles (par exemple, l'échelle linéaire personnalisable, les cases à cocher et les questions à choix multiples) et, surtout, les résultats peuvent être facilement exportés à des fins d'analyse statistique. D'après nos recherches en ligne, il semble que Google Forms soit, du moins pour le moment, le meilleur outil sans frais pour mener des enquêtes. Sur un ton plus léger, il serait apprécié que vous utilisiez un produit Google dans une initiative gérée par Google.

J'ai créé une enquête préliminaire avec des exemples de questions (accessible à l'adresse https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Le nombre de questions dans la version finale doit être compris entre 10 et 15. Pour obtenir des résultats concrets, je suggère d'utiliser principalement des questions à choix multiples, une échelle linéaire et quelques cases à cocher. L'échelle linéaire ne doit toutefois pas ressembler à un spectre complet, car elle ne fait que créer une confusion et les résultats risquent d'être fortement dispersés. Il ne doit y avoir au maximum deux questions ouvertes, sinon les résultats seront très dispersés et ne seront d'aucune utilité. Je pense que même un nombre très élevé de réponses ne poserait pas de problème, car les données peuvent être facilement exportées et analysées automatiquement à l'aide d'un logiciel statistique. En supposant que le nombre de réponses soit effectivement très élevé, l'analyse des questions ouvertes peut être un peu chronophage, mais je pense que ce ne sera pas trop compliqué. Après tout, un utilisateur moyen n'est pas susceptible d'écrire un essai sur l'état de la documentation. Dans le pire des cas, certaines réponses peuvent être simplement stockées pour une analyse ultérieure.

Guides graphiques:

Ma vision des guides graphiques (destinés à servir d'outils de navigation) repose sur une prémisse populaire selon laquelle (la plupart) des humains sont plus à même de traiter des structures visuelles simples que des informations purement textuelles. De plus, un diagramme thématique avec des lignes reliant des sujets d'intérêt similaires est sans aucun doute un atout très précieux pour les utilisateurs moins expérimentés (et pas seulement).

Pour les détails de l'implémentation, je propose d'utiliser le package TikZ. Tout d'abord, il s'agit d'un outil puissant qui ne risque pas d'être bientôt abandonné. Il offre également un résultat de haute qualité, une documentation très solide et est un sujet fréquent sur TeX StackExchange et d'autres forums grand public. Plus important encore, l'intégration d'un fichier TikZ (et plus précisément des nombreux liens hypertextes qu'il contient) à la documentation HTML ne semble pas poser de problèmes importants, grâce à l'existence de divers paquets et correctifs permettant d'intégrer une image TikZ dans du code HTML (par exemple, TeX4ht).

La question de la maintenance future des guides dans SciPy peut être facilement résolue en utilisant, par exemple, Overleaf (qui facilite la collaboration et offre un aperçu instantané) et des modèles prédéfinis que je fournirai. En principe, les guides graphiques ne sont pas très différents les uns des autres. La structure, la palette de couleurs et les formes vont plus ou moins être invariantes. Par conséquent, les remodelages et personnalisations ultérieurs ne poseront pas de problème.

(Veuillez consulter la version complète de la proposition, disponible dans le dossier GSoD partagé.)