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:
- Matplotlib
- Rédacteur technique:
- jeromev
- Nom du projet:
- Développer des chemins d'entrée Matplotlib
- Durée du projet:
- Durée standard (3 mois)
Project description
Introduction
La suggestion de projet de Matplotlib pour la saison des documents Google de cette année consiste à créer du contenu visant à présenter Matplotlib à de nouveaux utilisateurs. Pour le développement des chemins d'entrée Matplotlib, je propose une approche alternative à celle de la documentation actuelle. Je suis un nouvel rédacteur technique dans le secteur, mais j'ai mon expérience dans des domaines liés à l'éducation et à l'éducation. La rédaction technique et l'éducation s'articulent autour de points forts. Elles se concentrent sur la production de contenus faisant preuve d'empathie et permettant aux utilisateurs d'accomplir leurs tâches avec les ressources fournies.
Dans ce contexte, la documentation de Matplotlib bénéficierait d'une amélioration de l'empathie envers les nouveaux utilisateurs. À l'heure actuelle, une grande partie du matériel est constituée de données aléatoires et de visuels non étiquetés. Ils sont parfaits pour afficher rapidement les visuels et les fonctionnalités de Matplotlib. Cependant, pour une personne qui débute sur Matplotlib, il est difficile de traverser la transformation des données en visuels.
Un contexte dans une approche décrivant est une solution à cet obstacle. En rédigeant une procédure à la lumière d'un exemple réel, nous démontrons une compréhension de l'environnement dans lequel un utilisateur travaille. Cela améliore la relation entre la documentation et l'utilisateur en ce qui concerne l'atteinte d'un objectif ou l'attente d'une tâche.
Un utilisateur a un objectif dérivé cohérent. Par exemple, un data scientist d'une entreprise de chaussures doit présenter des données client à une équipe pour illustrer les tendances d'achat au fil du temps. Dans ce cas, l'utilisateur doit apprendre à naviguer dans Matplotlib et utiliser les outils de la bibliothèque pour effectuer la tâche à accomplir.
Avec du contexte supplémentaire pour étayer la documentation, un nouvel utilisateur peut plus facilement s'identifier au sujet. L'objectif dérivé de l'utilisateur est parallèle à la documentation. J'espère travailler vers la vision dont Tom Caswell, développeur principal, a évoqué lors d'un entretien en 2017 : "avoir quelqu'un qui puisse vraiment écrire et avoir de l'empathie pour les utilisateurs, afin qu'il étudie et rédige un livre d'introduction de 200 pages, qui constitue l'entrée principale de la documentation."
Approche alternative de l'écriture d'exposition
La documentation actuelle illustre les fonctionnalités de Matplotlib, c'est-à-dire les actions qu'un utilisateur peut effectuer avec la bibliothèque. Par exemple, un tutoriel suit souvent un modèle qui n'implique pas d'expliquer la méthode sous-jacente.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Souvent, avec de la documentation et une assistance pour la programmation, il est recommandé à l'utilisateur d'exécuter le code lui-même pour comprendre ce qui se passe. Même si une approche de la programmation améliore la compréhension du sujet par les utilisateurs, la courbe d'apprentissage des transformations comporte peu de ressources complémentaires. Cela peut être un défi accablant, car la documentation est limitée.
Fournir des diagrammes, des images ou d'autres éléments visuels supplémentaires contribuera à créer de nouvelles opportunités d'apprentissage. La structure ci-dessous peut également servir de modèle pour de nouveaux contenus. De plus, l'ajout d'images ou de graphiques non textuels peut bénéficier de fonctionnalités telles que les accroches et les coches. Dans certains cas, il est plus difficile de parcourir des images sans indiquer où ni comment le code est transformé en sortie exécutée. Je pense qu'il manque un élément visuel important qui pourrait favoriser une meilleure compréhension des sujets.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Cette approche alternative consistant à utiliser l'écriture exposant pour la documentation présente un potentiel énorme. Les utilisateurs ayant accès à divers concepts de transformation peuvent mieux identifier les stratégies sous-jacentes permettant de développer des visualisations des données. Ces connaissances peuvent aider les utilisateurs à innover et à tirer parti des fonctionnalités présentées par des exemples basés sur des cas d'utilisation réalistes.
Avec la popularité grandissante de Matplotlib, la cohérence de la facilité d'utilisation et de l'accessibilité témoigne de la réputation de la bibliothèque. Ces caractéristiques se prêtent à illustrer des modèles et des stratégies courantes qui peuvent apparaître non seulement dans le code, mais également dans la documentation. Si Matplotlib est un langage simple et standard pour la programmation, comme en témoignent son utilisation croissante et l'expansion de ses ressources, cela peut également être le cas pour la documentation technique.
Lorsque les utilisateurs rencontrent des problèmes, il est courant d'utiliser la recherche pour les résoudre. Plutôt que de considérer la recherche comme la méthode de navigation principale, il peut être plus efficace de demander aux utilisateurs de créer leur propre programme dans la documentation. Dans ce sens, un utilisateur recherche une solution à son problème, puis lorsqu'il rencontre un autre problème ou souhaite des informations supplémentaires, il utilise des liens intégrés et détaillés.
Cela impliquerait une architecture ascendante dans le système organisationnel. Pour chaque sujet de Matplotlib, un vaste réseau de liens vers des sujets d'affinité et des sujets informatifs contribuerait à créer un réseau solide. Sur ce réseau, un utilisateur est plus susceptible de continuer à utiliser la documentation lorsqu'il accède à son sujet et qu'il explore de plus en plus d'informations à son sujet.
Obstacles
Il y a toujours des défis avec un projet aussi complet et détaillé que cela. En tant que rédactrice technique plus récente dans le secteur, j'ai une expérience limitée de l'utilisation de Sphinx et ReST pour rédiger de la documentation. Je débute également avec Matplotlib et Git. S'attaquer à ces quatre systèmes et se familiariser avec leur utilisation pour la collaboration et la recherche prendra du temps. Je vais devoir déléguer du temps pendant la phase d'association avec la communauté et plus tôt afin de construire les bases nécessaires pour les parcours de niveau d'entrée. Pendant cette période, si je rencontre des problèmes avec des concepts et des principes fondamentaux, je devrai contacter la communauté pour obtenir de l'aide.
La coordination des efforts de collaboration entre les fuseaux horaires et les plates-formes en ligne nécessitera également quelques ajustements. Il existe de nombreux moyens de communication que les gens de tout le secteur utilisent, il est donc important de m'assurer que je suis accessible et accessible sur tous les supports. Je serai transparent dans l'établissement des priorités variables d'un bout à l'autre. Même si je débute tout juste dans ce genre de travail dans le secteur, je m'engage à assumer des responsabilités et à être ouvert aux commentaires et aux critiques. Je pense que ces qualités sont précieuses quel que soit le domaine.
En outre, l'augmentation des tests d'utilisabilité est une section de documentation qui, à mon avis, serait bénéfique pour les chemins d'entrée de Matplotlib. La réalisation d'enquêtes sur la facilité d'utilisation du contenu permet de fournir un profil d'un utilisateur, c'est-à-dire des personas. Les informations telles que l'expérience de l'utilisateur, son secteur d'activité et son historique de dépannage sont précieuses. Ces éléments contribuent à former le langage derrière la procédure. Lorsque l'écriture rencontre les lecteurs à leur niveau, le contenu va au-delà du simple but pédagogique.
La mise en place d'une pratique continue de tests d'utilisabilité constitue souvent de gros problèmes. Il est bien trop fréquent d'avoir eu recours à une seule instance de test, voire à une seule exécution, lors du développement de contenu. Des tests réguliers sur la facilité d'utilisation permettent d'orienter le récit du contenu. J'aimerais mettre en place un calendrier ou organiser des tests d'utilisabilité récurrents avec la communauté Matplotlib.
Conclusion
J'ai un peu d'expérience dans l'utilisation de Python ainsi que de Matplotlib pendant mon temps libre. Au cours des derniers mois, j'ai appris beaucoup de choses grâce à la documentation actuelle et à ma propre curiosité. J'ai également eu quelques vidéos et mentors à ce moment-là. J'ai encore beaucoup à apprendre et encore plus de marge de progression en créant mon propre programme de programmation qui m'intéresse.
Après avoir vu les idées de Matplotlib et de la communauté pour GSoD, je pense que ce serait une excellente expérience de développement pour améliorer mes compétences en tant que rédacteur technique et avoir l'opportunité d'en apprendre davantage auprès des personnes en coulisses. J'ai senti que ce projet Matplotlib était à la fois significatif et quelque chose qui me passionne en idéologie.
Pour travailler sur une refonte du guide d'utilisation, mon objectif en tant que rédacteur technique est d'aider les utilisateurs à accomplir les tâches qu'ils souhaitent sans être submergés par les fonctionnalités disponibles. Je crois que la meilleure documentation continuera de croître et de s'adapter aux utilisateurs et permettre à chacun d'accéder à ses propres solutions.