Projet Bokeh

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:

Bokeh

Rédacteur technique:

vis_verborum

Nom du projet:

Créer, lire et partager: optimiser la documentation de Bokeh

Durée du projet:

Durée standard (trois mois)

Project description

Créer, lire et partager: optimiser la documentation de Bokeh

1. Extrait

Bokeh est un outil extrêmement puissant pour créer des visualisations interactives basées sur le navigateur avec Python. Il dispose d'une base d'utilisateurs importante (502 000 téléchargements conda mensuels, 855 000 téléchargements PyPi) et d'un grand nombre de contributeurs (455 contributeurs sur GitHub). Il n'est donc pas surprenant que la vaste documentation de Bokeh s'est développée de façon organique. Par conséquent, il est parfois incohérent, difficile d'accès et complexe.

La saison de la documentation de Google offre une opportunité unique d'examiner et de réviser de manière ciblée la structure et le contenu de la documentation de Bokeh, et de s'assurer que la documentation, ainsi que les outils et les workflows associés, sont adaptés à l'avenir.

J'ai codé et documenté des projets Open Source avec Python et Sphinx (plus récemment, PyZillow et PyPresseportal). Mais ce qui me distingue des autres participants à la saison des documents de Google, c'est mon expérience dans le journalisme: j'ai travaillé dans des rédactions pendant plus de 13 ans, dont de nombreuses années en tant que rédacteur en chef et défenseur du changement numérique. En plus de mes fonctions journalistiques, j'ai eu de plus en plus de responsabilités liées à la conception et à la documentation de nouveaux outils numériques et guides de style, ainsi qu'à la formation du personnel de rédaction.

Après avoir récemment quitté l'Europe pour les États-Unis, j'ai décidé d'explorer de nouvelles façons de combiner mon enthousiasme pour la communication et le codage. J'ai trouvé que la rédaction technique était la combinaison optimale de mes compétences et de mes expériences en écriture et en technologie. Dans cette proposition, je vais expliquer comment je vais utiliser la saison des documents de Google pour optimiser la documentation de Bokeh: en rendant la création et la contribution à la documentation plus pratiques, en rendant la lecture de la documentation plus simple et en facilitant le partage des informations de la documentation avec d'autres personnes.

2. Situation actuelle

La documentation officielle de Bokeh se compose des unités principales suivantes:

• Documentation narrative: guide d'installation, guide de l'utilisateur, guide du développeur, notes de version
• Galerie et démos (exemples interactifs avec leur code source)
• Guide de référence (documentation basée sur les docstrings)
• Tutoriel (vaste collection de notebooks Jupyter, hébergés sur mybinder.org)
• Chaînes de documentation et aide sur les modèles pour les IDE
• Exemples et fichiers README dans le dépôt du projet

De plus, de nombreuses informations sont disponibles sur le forum d'assistance de Bokeh et sur Stack Overflow, où le développeur de Bokeh répond activement aux questions des utilisateurs, ainsi que sur le blog Medium de Bokeh.

La plupart des pages Web de la documentation sont créées avec Sphinx, à l'aide de plusieurs extensions Sphinx standards et personnalisées. Le guide de référence, par exemple, est généré à partir de docstrings, à l'aide d'extensions telles que "autodoc" et "bokeh_autodoc" personnalisées. Comme c'est la nature de la documentation développée naturellement, elle contient des redondances et des incohérences.

L'un des premiers éléments que j'ai remarqués lors de l'analyse de la documentation existante était l'absence de consignes de style claires pour la rédaction de la documentation. Le guide du développeur Bokeh contient des instructions de base. Toutefois, ce document ne contient pas beaucoup de conseils sur le style, en particulier concernant la documentation qui va au-delà des docstrings. Par conséquent, des problèmes stylistiques et structurels rendent l'accès aux informations contenues dans les documents plus difficile, en particulier pour les nouveaux arrivants.

Exemple :

• L'utilisation de noms, de gronflements et de mots inhabituels au lieu de verbes clairs et forts rend certains textes inutilement compliqués : "L'observation principale est que l'utilisation typique consiste à créer des objets tracé avec la fonction figure()". Ce texte doit être reformulé pour faciliter la lecture. Par exemple : « La fonction figure() est la fonction la plus couramment utilisée pour créer des objets de tracé. »
• Certaines phrases sont très longues et difficiles à comprendre: "Ensuite, nous pouvons appeler vbar avec la liste des facteurs de nom de fruit comme coordonnée X, la hauteur de la barre comme coordonnée supérieure et éventuellement toute largeur ou autre propriété que nous souhaitons définir". Les phrases plus longues doivent être divisées en phrases plus courtes ou en listes à puces. La simplification des phrases sera particulièrement utile pour les utilisateurs souffrant de dyslexie ou pour les personnes dont l'anglais n'est pas la langue maternelle (voir l'issue 10160).
• Utilisation incohérente des termes "vous" et "nous", ce qui prête à confusion et détourne l'attention: "Deux méthodes de base peuvent être utilisées, en fonction de votre cas d'utilisation" et "Nous pouvons représenter toutes les séries d'années à l'aide d'appels distincts" (deux exemples sur la même page). Certaines pages s'adressent même aux lecteurs de différentes manières, par exemple: "Les utilisateurs peuvent avoir à installer des dépendances supplémentaires" ou "On peut créer des mises en page plus complexes".
• Des fautes de frappe, des mots manquants et superflus, ainsi que des erreurs grammaticales interrompent la lecture et endommagent la crédibilité des informations: "Bokeh simplifie la création d'histogrammes" ou "Reportez-vous à la section sur les Glyphs du guide de l'utilisateur".
• Les incohérences structurelles peuvent être frustrantes pour les lecteurs, comme le fait d'avoir des exemples bien annotés sur une page et aucune explication des exemples sur une autre page.

La page de destination de la documentation de Bokeh est plutôt courte et n'inclut pas d'informations sur toutes les ressources disponibles (aucune mention de la vaste bibliothèque de docstrings et de fonctions d'aide du modèle, des forums d'assistance, des démonstrations ou du blog Medium). Cela rend également plus difficile la prise en main de Bokeh par les nouveaux utilisateurs.

3. Objectifs

Pour utiliser le plus efficacement possible la phase de développement d'un document de 11 semaines, je vais me concentrer sur trois éléments clés:

3.1. Améliorer la création des documents

La majeure partie de la documentation de Bokeh est rédigée par des contributeurs qui l'incluent dans les demandes d'extraction de nouvelles fonctionnalités et de corrections de bugs. Bien que j'utilise une partie de la phase de développement de la documentation pour modifier et refactoriser les documents existants, je vais mettre l'accent sur la création de workflows permettant de créer et de gérer la documentation de manière pérenne: il doit être aussi simple que possible pour les contributeurs de maintenir un niveau de documentation élevé et cohérent.

Je vais m'en assurer de deux manières:

• Je vais créer un ensemble de consignes de style pratiques et simples à inclure dans le guide du développeur existant. Ces consignes concernent le style, la grammaire et la structure. De plus, je vais utiliser des canaux de communication internes tels que Slack pour m'assurer que les contributeurs de Bokeh connaissent les consignes de style. Je proposerai également des formations individuelles et des sessions de questions-réponses pour l'équipe.
• Je vais travailler avec l'équipe de base pour trouver un ensemble d'outils optimal pour le contrôle qualité de la documentation, qui sera ajouté aux workflows existants de Bokeh pour les PR (pull requests) et l'intégration continue. Selon les exigences de l'équipe, cela peut impliquer d'ajouter des outils tels que pydocstyle, proselint ou sphinxcontrib-spelling à la suite de test de Bokeh, à la configuration pré-commit ou aux actions GitHub. J'ai ajouté un prototype fonctionnel aux actions GitHub de l'un de mes propres projets Open Source.

3.2. Améliorer la lecture de la documentation

L'objectif d'une bonne documentation est de permettre aux utilisateurs actuels et potentiels de trouver facilement les informations exactes dont ils ont besoin et de pouvoir les utiliser aussi efficacement que possible.

Le style et la structure sont des facteurs clés de l'usabilité d'un texte: rédiger une documentation dans un style clair et cohérent permet aux lecteurs de saisir rapidement les informations, sans distraction ni langage superflu. La structure simple et transparente de la documentation permet de trouver facilement et rapidement les informations pertinentes.

Je vais me concentrer sur ces deux aspects, en mettant l'accent sur l'usabilité pour les nouveaux utilisateurs. Cela inclut un examen approfondi de la documentation narrative, axé sur le guide de l'utilisateur. Je vais également revoir la page de destination de la documentation pour mieux répondre aux différentes audiences cibles et m'assurer que chaque utilisateur peut trouver rapidement les ressources appropriées.

Tout comme pour l'amélioration de la création des documents décrits ci-dessus, je vais me concentrer sur l'établissement des bases pour de futures améliorations et sur des normes élevées en permanence pour la documentation de Bokeh.

3.3. Améliorer le partage des documents

De plus en plus de discussions sur Bokeh ont lieu sur des plates-formes tierces. Nombre de ces plates-formes utilisent des métadonnées telles que OpenGraph de Facebook pour inclure des aperçus enrichis des liens. OpenGraph est utilisé par des services tels que Facebook, Twitter, LinkedIn, Slack et iMessage. Le forum Discourse de Bokeh utilise également OpenGraph pour afficher les aperçus des liens.

Pour utiliser cette technologie, j'ajouterai des métadonnées aux pages Web générées par Sphinx de Bokeh, comme décrit dans l'issue 9792. Le moyen le plus efficace consiste à utiliser une extension Sphinx dédiée. Il y a quelques jours, une toute première version d'une extension Sphinx pour les données OpenGraph a été publiée sur GitHub. Je vais utiliser une partie de la phase de développement de la documentation pour améliorer cette extension à utiliser avec la documentation de Bokeh.

J'ai également créé un prototype que j'utilise avec succès dans l'un de mes propres projets Open Source, PyPresseportal. Cette extension collecte automatiquement des informations pertinentes telles que le titre, la description, l'image et l'URL. Il insère ensuite ces informations dans le code HTML généré par Sphinx sous forme de balises OpenGraph.

La prochaine étape du développement de cette extension consistera à introduire des directives personnalisées pour définir manuellement les métadonnées OpenGraph (comme les directives "meta" existantes de docutil). Les métadonnées générées automatiquement ne sont utilisées qu'en remplacement, si aucune donnée saisie manuellement n'est disponible.

L'implémentation des données structurées est beaucoup plus complexe. Je vais donc me concentrer principalement sur l'inclusion de métadonnées OpenGraph de haute qualité pour la documentation de Bokeh. Tout le travail effectué pour prendre en charge OpenGraph servira également de base à la prise en charge des données structurées.

Des membres des communautés Sphinx et ReadTheDocs ont exprimé leur intérêt pour le développement d'extensions pour OpenGraph et les données structurées (dans les numéros #1758 et #5208, par exemple). Je vais m'assurer de travailler en étroite collaboration avec elles.

4. Livrables

Pour résumer, voici les livrables que je m'attends à obtenir à la fin de la saison des documents:

• Consignes de style pour la documentation des contributeurs Bokeh
• Modification des workflows de PR et de CI pour inclure un contrôle automatique de la qualité de la documentation
• Guide de l'utilisateur modifié et restructuré
• Page de destination de la documentation révisée
• Métadonnées OpenGraph incluses dans les pages Web de la documentation et une extension Sphinx fonctionnelle

De plus, je vais tenir un "doclog" pour documenter mon parcours pendant la saison des documents de Google sur mon site Web/Medium personnel ou sur le blog Medium de Bokeh. Il servira également de base au rapport sur le projet pour Google. Je vais effectuer tout le travail de manière transparente, sous la forme de problèmes GitHub et de demandes d'extraction, dans la mesure du possible.

5. Chronologie

Avant la phase de cohésion au sein de la communauté: je participe déjà activement à plusieurs discussions sur le dépôt GitHub de Bokeh et j'ai été en contact avec Bryan Van de Ven et Pavithra Eswaramoorthy, les mentors de Bokeh pour la saison des documents de Google. Je resterai actif dans la conversation sur le Bokeh et je me familiariserai également davantage avec le Bokeh en créant et en publiant des visualisations.

Phase de renforcement des liens au sein de la communauté (17/08-13/09):

• Apprendre à connaître l'équipe de base, affiner le plan du projet en échange avec des mentors
• Définir un calendrier et des canaux de communication pour les rapports et les commentaires réguliers avec les mentors
• Être actif sur le canal Slack de Bokeh pour informer tous les contributeurs Bokeh intéressés sur la saison de la documentation de Google et les objectifs de la phase de développement de la documentation
• Recueillir les commentaires des contributeurs Bokeh pour affiner davantage le plan de la phase de développement de la documentation

Phase de développement de la documentation

Semaine 1, du 14 au 20 septembre:

• Commencer à auditer et à modifier la documentation narrative
• Commencer à rédiger des consignes de style

Semaine 2, du 21 au 27 septembre:

• Continuer à travailler sur les consignes de style
• Continuer à modifier la documentation narrative
• Commencer à revoir la page de destination de la documentation

Semaine 3, du 28/09 au 04/10:

• Finaliser les consignes de style
• Finaliser la page de destination de la documentation

Semaine 4, du 5 au 11 octobre:

• Finaliser la modification de la documentation narrative
• Discuter avec l'équipe principale de Bokeh de l'intégration d'outils de contrôle qualité des documents dans les workflows PR/CI

Semaine 5, du 12 au 18 octobre:

• Organiser une session de questions/réponses avec les contributeurs de Bokeh sur Slack pour discuter des consignes de style, des améliorations apportées à la documentation narrative et des workflows de PR/CI
• Commencer à développer ma preuve de concept existante pour les métadonnées OpenGraph en une extension Sphinx déployable
• Réviser les directives de style en fonction des commentaires de la séance de questions-réponses avec des contributeurs Bokeh

Semaine 6, du 19 au 25 octobre:

• Début des tests des outils de contrôle de la qualité des documents dans les workflows de PR et de CI
• Poursuivre le développement de l'extension Sphinx pour les métadonnées

Semaine 7, 26/10 - 01/11:

• Test de l'extension Sphinx
• Deuxième session de questions/réponses avec les contributeurs Bokeh sur Slack
• Réviser les livrables en fonction des commentaires de la deuxième session de questions/réponses

Semaine 8, du 2 au 8 novembre:

• Déploiement de l'extension Sphinx, publication d'une documentation narrative améliorée et d'une page de destination de documentation

Semaine 9, du 9 au 15 novembre:

• Déployer des outils de contrôle de la qualité des documents dans les workflows de PR et de CI
• Mise à jour et publication du guide du développeur pour y inclure les consignes de style et les ajouts de workflows pour les demandes d'informations et la CI

Semaine 10, du 16 au 22 novembre:

• Finaliser les tâches restantes

Semaine 11, du 23 au 29 novembre:

• Commencer à rédiger un rapport de projet
• Commencer à rédiger l'évaluation du projet

Phase de finalisation du projet

Semaine 12, du 30/11 au 5/12:

• Finaliser et envoyer le rapport de projet

Semaine 13, 03/12 - 10/12:

• Finaliser et envoyer l'évaluation du projet

À la fin de la saison des documents Google:

• J'espère rester impliqué dans le développement de Bokeh et continuer à travailler sur sa documentation.
• Je prévois de poursuivre le développement d'une extension Sphinx pour les métadonnées OpenGraph/données structurées.
• J'espère utiliser mon expérience dans le journalisme et mon réseau existant pour promouvoir Bokeh comme outil de journalisme de données. Par exemple, en écrivant sur Bokeh en pensant à un public journalistique ou en donnant des conférences sur l'utilisation de Bokeh dans un contexte journalistique.

6. À propos de moi

Je suis à l'origine journaliste, avec une expérience dans les actualités télévisées, en ligne et radio. En tant que rédacteur en chef et journaliste dans les actualités télévisées et numériques, j'ai acquis des années d'expérience en rédaction et en révision. En parallèle, j'ai travaillé sur plusieurs projets de promotion de la transformation numérique et de l'automatisation. J'ai rédigé de nombreux manuels sur les outils et les workflows numériques, ainsi que des guides de style et des stratégies de communication pour des marques d'actualités numériques. J'ai également formé les membres de l'équipe à utiliser ces outils.

J'ai toujours été attiré par les intersections entre la communication et la technologie. Un tout nouveau monde s'est ouvert à moi lorsque j'ai appris à coder en Python: j'ai pu effectuer des analyses et des visualisations de données pour le journalisme de données, par exemple. Apprendre à coder m'a également permis de collaborer activement avec des ingénieurs logiciels pour développer des outils numériques pour les workflows de la rédaction.

Les manuels et documents que j'ai rédigés dans mon précédent emploi ne sont malheureusement pas publics. Je me concentre donc désormais sur une plus grande implication dans les projets Open Source (voir exemples ci-dessous). J'ai basé mon travail de rédactrice technique sur des guides de style tels que le guide de style de la documentation pour les développeurs de Google et le guide de style de Microsoft. J'utilise régulièrement GitHub, Slack et Linux. J'ai rédigé des documentations narratives, ainsi que des docstrings et des indications de type, à l'aide d'outils tels que Sphinx, Mypy et Sphinx autodoc.

Je suis actuellement indépendant. Mon emploi du temps me permet de travailler sur la documentation de Bokeh pendant environ 25 heures par semaine pendant la phase de développement de la documentation. Je travaille dans le fuseau horaire du Pacifique, mais je serai ravi de m'adapter aux horaires et aux besoins de l'équipe.

7. Exemples récents de documentation Open Source

• PyZillow: PyZillow est un wrapper Python pour l'API du site Web immobilier Zillow.com. En plus de fournir du code et d'être l'un des responsables de ce code, j'ai rédigé la documentation complète. J'ai utilisé Sphinx pour la documentation narrative et comme référence sur le module. J'ai créé la référence du module avec l'extension Sphinx autodoc, d'après les docstrings que j'ai ajoutées au code.

• PyPresseportal: PyPresseportal est un wrapper Python de l'API du site Web presseportal.de. Le site Web presseportal.de est l'un des plus grands distributeurs de communiqués de presse et d'annonces de relations avec les investisseurs en Allemagne. Par exemple, presque tous les services de police et de pompiers utilisent ce service pour distribuer leurs communiqués de presse. Après avoir utilisé l'API pendant de nombreuses années en tant que journaliste, j'ai décidé de développer une interface Python pour accéder aux vastes ressources de données du site Web en tant qu'objets Python. J'ai rédigé le code et toute la documentation basée sur Sphinx.