Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.
Résumé du projet
- Organisation Open Source:
- Matplotlib
- Rédacteur technique:
- jeromev
- Nom du projet:
- Développer des chemins d'accès Matplotlib
- Durée du projet:
- Durée standard (trois mois)
Project description
Introduction
La suggestion de projet de Matplotlib pour la Google Season of Docs de cette année consiste à créer du contenu permettant de présenter Matplotlib aux nouveaux utilisateurs. Pour le développement de chemins d'accès Matplotlib, je propose une approche différente de celle de la documentation actuelle. Je suis nouveau dans le métier de rédacteur technique, mais mon parcours est axé sur l'éducation et les domaines connexes. La rédaction technique et l'enseignement présentent de fortes similitudes, qui consistent à produire du contenu qui fait preuve d'empathie et permet aux utilisateurs d'accomplir leurs tâches avec les ressources fournies.
Dans ce contexte, la documentation Matplotlib pourrait être améliorée pour faire preuve d'empathie envers les nouveaux utilisateurs. La plupart du contenu actuel se compose de données aléatoires et de visuels non étiquetés. Ils sont excellents pour afficher rapidement les visuels et les fonctionnalités de Matplotlib. Toutefois, dans le cas d'une personne qui ne connaît pas Matplotlib, il est difficile de transformer les données en visuels.
Un contexte dans une approche expositive est une solution à cet obstacle. En écrivant une procédure à partir 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 termes d'atteinte d'un objectif ou d'attentes de réalisation d'une tâche.
Un utilisateur a un objectif dérivé cohérent. Par exemple, un data scientist travaillant dans 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 à exploiter les outils de la bibliothèque pour accomplir la tâche à accomplir.
Avec un contexte supplémentaire pour étayer la documentation, un nouvel utilisateur peut être plus en mesure de s'identifier au sujet. L'objectif dérivé de l'utilisateur est parallèle à la documentation. J'espère poursuivre la vision du développeur en chef Tom Caswell lors d'un entretien en 2017 : "d'avoir quelqu'un capable d'écrire et ayant de l'empathie pour les utilisateurs, de suivre et d'écrire un livre de 200 pages intitulé "Intro to Matplotlib" (Introduction à Matplotlib) qui constituera l'entrée principale de la documentation."
Alternative Approach of Expository Writing
La documentation actuelle présente les fonctionnalités de Matplotlib, c'est-à-dire les tâches qu'un utilisateur peut effectuer avec la bibliothèque. Par exemple, un tutoriel suit souvent un modèle qui n'implique pas d'explication de la méthode sous-jacente.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Souvent, avec la documentation et l'assistance de programmation, il est recommandé à l'utilisateur d'exécuter le code lui-même pour comprendre ce qui se passe. Bien qu'un état d'esprit de programmation améliore la compréhension du sujet par l'utilisateur, la courbe d'apprentissage des transformations est peu étayée. Cela peut être un défi de taille, car la documentation est limitée.
Fournir des diagrammes, des images ou d'autres 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 d'éléments graphiques non textuels peut être utile avec des fonctionnalités telles que les accroches et les repères. Il arrive que les images soient plus difficiles à parcourir sans indication de la façon dont le code est transformé en sortie exécutée. Je pense qu'il manque un élément visuel marqué 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 qui consiste à utiliser l'écriture exposant pour la documentation présente un potentiel énorme. En voyant différents concepts de transformation, les utilisateurs pourront mieux identifier les stratégies sous-jacentes de développement de visualisations de données. Ces connaissances peuvent aider les utilisateurs à innover et à profiter des fonctionnalités présentées par des exemples basés sur des cas d'utilisation réalistes.
À mesure que Matplotlib gagne en popularité, 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 permettent de mettre en évidence des tendances et des stratégies courantes qui peuvent apparaître non seulement dans le code, mais aussi dans la documentation. Si Matplotlib est simple et standard pour les utilisateurs à programmer, comme le montre l'évidence de son utilisation croissante et de l'augmentation de ses ressources, il peut également en être de même pour la documentation technique.
Lorsque les utilisateurs rencontrent des problèmes, il est courant qu'ils utilisent la recherche pour les résoudre. Plutôt que de s'appuyer sur la recherche comme principale méthode de navigation, il peut être plus efficace de demander aux utilisateurs de créer leur propre programme de formation dans la documentation. En ce sens, un utilisateur recherche une solution à son problème, puis lorsqu’il rencontre un autre problème ou voudrait des informations supplémentaires, il utilisera des liens intégrés et complets tout au long du problème.
Cela implique une architecture ascendante dans le système organisationnel. Pour chaque sujet de Matplotlib, un réseau riche de liens vers des affinités de sujets et des sujets d'information aiderait à créer un réseau robuste. Sur l'ensemble de 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 sur ce sujet.
Obstacles
Il y a toujours des défis avec un projet aussi complet et aussi détaillé que cela. En tant que rédacteur technique novice dans le secteur, j'ai une expérience limitée de l'utilisation de Sphinx et de ReST pour rédiger de la documentation. Je suis également débutant en ce qui concerne Matplotlib et Git. S'attaquer à ces quatre systèmes et s'habituer à les utiliser pour la collaboration et la recherche prendra du temps. Je devrai consacrer du temps à la phase de consolidation de la communauté et avant cela afin de poser les bases nécessaires aux parcours d'entrée. Pendant cette période, si j'ai des problèmes avec les concepts et les principes de base, je devrai contacter la communauté pour obtenir une aide supplémentaire.
La coordination des efforts collaboratifs entre les fuseaux horaires et les plates-formes en ligne nécessitera également des ajustements. Tout le secteur utilise de nombreuses voies de communication. Il s'agit donc de m'assurer que je suis accessible et accessible sur tous les supports. Je serai transparent dans la hiérarchisation des attentes différentes tout au long du processus. Bien que je ne commence tout juste à m'engager dans ce type de travail dans le secteur, je m'engage à m'en tenir responsable et à être ouvert aux commentaires et aux critiques. Je pense que ces qualités sont utiles dans tous les domaines.
De plus, l'augmentation des tests d'utilisabilité est une section de documentation qui, selon moi, bénéficierait des chemins d'accès de Matplotlib. Mener des enquêtes d'utilisabilité concernant le contenu permet de fournir un profil d'utilisateur, c'est-à-dire des personas. Des informations telles que l'expérience de l'utilisateur, son secteur d'activité et son historique de dépannage sont utiles. Ces éléments contribuent à définir le langage qui sous-tend la procédure. Lorsque le contenu est adapté au niveau des lecteurs, il ne se limite plus à un rôle purement pédagogique.
Les difficultés les plus importantes résident souvent dans la mise en place d'une pratique continue des tests d'utilisabilité. Il est bien trop courant qu'un seul test ait été effectué, voire pas du tout, pendant le développement du contenu. Les tests d'utilisabilité réguliers contribuent à orienter le récit du contenu. J'aimerais pouvoir définir un calendrier ou organiser des tests d'utilisabilité récurrents avec la communauté Matplotlib.
Conclusion
J'ai un peu d'expérience avec Python et Matplotlib pendant mon temps libre. Tout ce que j'ai appris tout seul ces derniers mois, c'est grâce à la documentation actuelle et à ma curiosité. J'ai également suivi quelques vidéos et conseils de mentors. J'ai encore beaucoup à apprendre et encore plus de marge de progression à mesure que je crée 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'occasion d'en apprendre davantage auprès des personnes qui travaillent en coulisses. J'ai trouvé que ce projet Matplotlib était à la fois pertinent et en phase avec mes convictions.
En tant que rédacteur technique, mon objectif est d'aider les utilisateurs à accomplir les tâches qu'ils souhaitent effectuer sans être submergés par les fonctionnalités disponibles. Je pense que la meilleure documentation continuera de croître et de s'adapter aux utilisateurs, et permettra à chacun de trouver ses propres solutions.