Projet SciPy

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:

SciPy

Rédacteur technique:

mkg33

Nom du projet:

Documentation axée sur l'utilisateur et restructuration approfondie

Durée du projet:

Durée standard (3 mois)

Project description

Motivation:

J'ai l'intention de travailler à la refactorisation de la documentation existante, afin qu'elle soit facilement accessible aux utilisateurs ayant des besoins différents. Il va sans dire qu'un chercheur s'intéresse très probablement aux fonctionnalités avancées et subtiles, tandis qu'un utilisateur sans expertise préalable apprécie les guides et diagrammes étape par étape.

Je souhaite poursuivre ce projet pour des raisons personnelles et professionnelles: tout d'abord, j'aimerais 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 manquante) dans d'autres logiciels et je me demande toujours combien plus rapidement (si c'est tout !) que les utilisateurs pourraient apprendre à utiliser le code s'ils avaient reçu un guide complet.

Objectifs :

Mon but est d'améliorer la documentation SciPy existante aussi bien au niveau du contenu que des images. La caractéristique la plus importante de mon approche de ce problème est le déploiement et l'analyse de l'enquête utilisateur, c'est-à-dire une courte enquête menée en ligne permettant à divers utilisateurs d'exprimer leurs besoins concernant la documentation. Je crois fermement que leurs opinions doivent être la source d'inspiration (comment créer une documentation plus conviviale ?).

En ce qui concerne la réalisation du projet lui-même, la première phase impliquera de concevoir et d'analyser l'enquête utilisateur, ainsi que de s'attaquer à plusieurs problèmes stylistiques que j'ai remarqués dans la documentation actuelle. Il peut s'agir, par exemple, d'un manque de cohérence (tableaux bidimensionnels se produisant à côté de tableaux à deux dimensions), de phrases compliquées à réécrire, ou du manque d'ordre alphabétique dans certaines sous-pages. La deuxième phase sera axée sur l'introduction de guides graphiques contenant des liens hypertexte vers les sujets pertinents (en fonction des résultats de l'enquête et d'autres demandes de la communauté). À long 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 et surtout, je souhaite écrire de nouveaux tutoriels (en fonction des besoins actuels de la communauté).

Enquête utilisateur:

Concernant l'enquête utilisateur, 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 offre une interface visuelle attrayante, les options d'enquête les plus utiles (par exemple, échelle linéaire personnalisée, cases à cocher et choix multiples) et, surtout, permet d'exporter facilement les résultats à des fins d'analyse statistique. D'après des recherches en ligne, il semble que Google Forms soit, du moins pour l'instant, le meilleur outil sans frais pour réaliser des enquêtes. En revanche, il serait intéressant que nous utilisions un produit Google dans le cadre d'une initiative Google.

J'ai créé une enquête préliminaire contenant des exemples de questions (vous pouvez y accéder à l'adresse https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Un nombre raisonnable de questions dans la version finale devrait être compris entre dix et quinze. Pour obtenir des résultats concrets, je vous conseille d'utiliser principalement des questions à choix multiples, une échelle linéaire et quelques cases à cocher. Cependant, l'échelle linéaire ne doit pas ressembler à un spectre complet (elle ne fait que créer de la confusion et les résultats sont susceptibles de souffrir d'une dispersion élevée). Le nombre de questions ouvertes ne doit pas dépasser deux. Sinon, les résultats seront très dispersés et ne seront pas du tout utiles. Je pense que même un très grand nombre de réponses ne poserait aucun problème, car les données peuvent être facilement exportées et analysées automatiquement à l'aide d'un logiciel statistique. Si on part du principe que le nombre de réponses est effectivement très élevé, l'analyse des questions ouvertes pourrait prendre un peu de temps, mais je présume que ce ne sera pas accablant. Après tout, il est peu probable qu'un utilisateur moyen rédige un dissertation sur l'état de la documentation. Dans le pire des cas, certaines réponses peuvent simplement être stockées pour une analyse ultérieure.

Guides graphiques:

Ma vision des guides graphiques (destinés à servir d'outils de navigation) repose sur un principe répandu selon lequel les humains sont plus aptes à traiter les structures visuelles simples que les informations purement textuelles. De plus, un diagramme axé sur un thème 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).

Concernant les détails de l'implémentation, je propose d'utiliser le package TikZ. Avant tout, il s'agit d'un outil puissant qui ne risque pas d'être bientôt abandonné. Il offre également des résultats de haute qualité, dispose d'une documentation très complète, et fait l'objet de discussions fréquentes sur TeX StackExchange et sur d'autres forums grand public. Plus important encore, l'intégration d'un fichier TikZ (plus précisément, les nombreux liens hypertextes) avec la documentation HTML ne semble pas poser de problèmes importants en raison de l'existence de divers packages et correctifs pour intégrer une image TikZ en 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 fournis. Fondamentalement, les guides graphiques ne sont pas susceptibles de différer grandement les uns des autres. La structure, la palette de couleurs et les formes étant plus ou moins invariantes, le remodelage ultérieur et une personnalisation plus avancée ne seront pas un problème.

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