Projet Bokeh

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:

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 (3 mois)

Project description

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

1. Abstraite

Bokeh est un outil extrêmement puissant pour créer des visualisations interactives, basées sur un navigateur avec Python. Sa base d'utilisateurs est importante (502 000 téléchargements de conda par mois, 855 000 téléchargements PyPi) et un grand nombre de contributeurs (455 contributeurs sur GitHub). Il n'est pas surprenant que la vaste documentation de Bokeh s'y développe naturellement. Et donc, dans des endroits, incohérents, difficiles d'accès et compliqués.

Le programme Season of Docs de Google offre une occasion unique de revoir et de réviser la structure et le contenu de la documentation de Bokeh, et de s'assurer que la documentation ainsi que les outils et workflows associés sont pérennes.

J'ai codé et documenté des projets Open Source avec Python et Sphinx (dernièrement: PyZillow et PyPresseportal). Mais ce qui fait de moi une participante unique à cette saison des documents Google, c'est mon parcours en journalisme: j'ai travaillé dans les rédactions pendant plus de 13 ans, avec de nombreuses années en tant que rédacteur en chef et défenseur du changement numérique. En plus de mes fonctions de journalisme, j'avais de plus en plus de responsabilités dans la conception et la documentation de nouveaux outils numériques et de nouveaux guides de style, ainsi que dans la formation du personnel de salle de rédaction.

Après avoir récemment quitté l'Europe pour les États-Unis, j'ai décidé de chercher de nouvelles façons de rassembler ma passion pour la communication et le codage. J'ai trouvé que la rédaction technique était la combinaison optimale entre mes compétences et mes expériences rédactionnelles et techniques. Dans cette proposition, je vais vous expliquer comment optimiser la documentation de Bokeh avec Season of Docs de Google: en facilitant la création et la contribution à la documentation, en facilitant la lecture de la documentation et en facilitant le partage des informations qu'elle contient avec d'autres personnes.

2. Situation actuelle

La documentation officielle de Bokeh comprend les unités principales suivantes:

• Documentation narrative: guide d'installation, guide de l'utilisateur, guide du développeur, notes de version
• Galerie et démonstrations (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é sur mybinder.org)
• Aide concernant les docstrings et les modèles pour les IDE
• Exemples et fichiers README dans le dépôt du projet

De nombreuses informations sont également 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 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". Tout comme la documentation organique, elle comporte des redondances et des incohérences.

L'une des premières choses que j'ai remarquées en analysant la documentation existante était le manque de directives de style claires pour la rédaction de la documentation. Le guide du développeur Bokeh contient quelques instructions de base. Cependant, ce document ne contient pas beaucoup d'instructions sur le style, notamment en ce qui concerne la documentation qui va au-delà des docstrings. Par conséquent, des problèmes stylistiques et structurels compliquent l'accès aux informations contenues dans les documents, en particulier pour les nouveaux arrivants.

Exemple :

• L'utilisation de noms, de gronde et de mots peu courants au lieu de verbes clairs et forts rend une partie du texte inutilement compliquée : "La principale observation est que l'utilisation typique implique la création d'objets de 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, ce qui les rend difficiles à comprendre: "Ensuite, nous pouvons appeler vbar avec la liste des facteurs de nom du fruit en tant que coordonnée x, la hauteur de la barre comme coordonnée supérieure, et éventuellement la largeur ou d'autres propriétés que nous souhaitons définir.". Les phrases longues doivent être divisées en phrases plus courtes ou listes à puces. Simplifier les phrases est particulièrement utile pour les utilisateurs dyslexiques ou ceux qui n'utilisent pas l'anglais comme langue maternelle (voir le problème n° 10160).
• Utilisation incohérente de "vous" et "nous", ce qui prête à confusion et peut détourner l'attention: "Vous pouvez utiliser deux méthodes de base, selon votre cas d'utilisation" et "Nous pouvons tracer les séries de l'année à l'aide d'appels distincts" (deux exemples tirés d'une même page). Certaines pages s'adressent aux lecteurs de différentes manières, par exemple: "les utilisateurs devront peut-être installer des dépendances supplémentaires" ou "il peut créer des mises en page plus complexes".
• Des fautes de frappe, des mots manquants et superflus, ainsi que des erreurs grammaticales brisent le flux de lecture et nuisent à la crédibilité de l'information: "Bokeh facilite la création de graphiques à barres basiques" ou "Voir la section 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 (pas de mention de la vaste bibliothèque de docstrings et de fonctions d'aide des modèles, des forums d'assistance, des démonstrations ou du blog Medium). Il est également plus difficile pour les nouveaux utilisateurs de commencer à utiliser Bokeh.

3. Objectifs

Pour tirer le meilleur parti de la phase d'élaboration des documents de onze semaines, je vais me concentrer sur trois éléments clés:

3.1. Améliorer la création de documents

La plupart de la documentation de Bokeh est rédigée par des contributeurs qui les incluent dans les demandes d'extraction pour de nouvelles fonctionnalités et les corrections de bugs. Bien que je profite d'une partie de la phase de développement du document pour modifier et refactoriser les documents existants, je vais mettre l'accent sur la pérennité des flux de travail de création et de gestion de la documentation: il doit être aussi facile que possible pour les contributeurs de maintenir un niveau de documentation toujours élevé.

Pour cela, deux approches sont possibles:

• Je vais créer un ensemble de consignes de style pratiques et simples à inclure dans le guide du développeur existant. Ces directives traitent du style, de la grammaire et de la structure. De plus, j'utiliserai des canaux de communication internes tels que Slack pour m'assurer que les contributeurs de Bokeh sont au courant des directives de style. Je proposerai également une formation individuelle et des séances de questions-réponses pour l'équipe.
• Avec l'équipe de base, je vais trouver un ensemble d'outils optimal pour le contrôle qualité de la documentation, qui sera ajouté aux workflows existants de Bokeh pour les demandes d'extraction et le CI (intégration continue). En fonction des exigences de l'équipe, cela pourrait impliquer l'ajout d'outils tels que pydocstyle, proselint ou sphinxcontrib-spelling à la suite de tests de Bokeh, à la configuration de pré-commit ou à des actions GitHub. J'ai ajouté une démonstration de faisabilité fonctionnelle aux actions GitHub d'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 exactement les bonnes informations et de les utiliser le plus efficacement possible.

Les principaux facteurs de la facilité d'utilisation d'un texte sont son style et sa structure: un texte rédigé dans un style clair et cohérent permet aux lecteurs de assimiler rapidement l'information, sans distractions ni langage superflu. Une structure simple et transparente de la documentation permet de trouver facilement et rapidement des informations pertinentes.

Je vais me concentrer sur ces deux aspects, en particulier sur la facilité d'utilisation pour les nouveaux utilisateurs. Cela comprend un examen approfondi de la documentation narrative, centrée sur le guide de l'utilisateur. Je vais également remanier 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 bonnes ressources.

Tout comme pour améliorer la création des documents décrits ci-dessus, je vais m'efforcer de poser les bases des futures améliorations et de définir des normes élevées et constantes pour la documentation de Bokeh.

3.3. Améliorez le partage des documents

Le bokeh fait de plus en plus l'objet de discussions sur les plates-formes tierces. Nombre d'entre elles utilisent des métadonnées telles que l'OpenGraph de Facebook pour inclure des aperçus détaillés 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, je vais ajouter des métadonnées aux pages Web générées par le Sphinx de Bokeh, comme indiqué dans le numéro 9792. Le moyen le plus efficace serait d’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 afin d'améliorer cette extension pour l'utiliser avec la documentation de Bokeh.

J'ai également créé une démonstration de faisabilité que j'utilise avec succès dans l'un de mes propres projets Open Source, PyPresseportal. Cette extension collecte automatiquement les 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.

L'étape suivante du développement de cette extension consisterait à 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.

La prise en charge des données structurées est beaucoup plus complexe, donc je vais me concentrer principalement sur l'inclusion de métadonnées OpenGraph de haute qualité pour la documentation de Bokeh. En même temps, tout le travail lié à la prise en charge d'OpenGraph jetera les bases de la prise en charge des données structurées.

Les membres des communautés Sphinx et ReadTheDocs ont exprimé leur intérêt pour le développement d'extensions pour OpenGraph et Structured Data (dans les numéros 1758 et 5208, par exemple), et je vais m'assurer de travailler en étroite collaboration avec eux.

4. Livrables

Pour résumer, voici les livrables que je m'attends à voir avec Season of Docs:

• Consignes de style de documentation pour les contributeurs Bokeh
• Révision des flux de travail des relations publiques et de CI pour inclure un contrôle automatisé 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 extension Sphinx fonctionnelle

En outre, je conserverai un « doclog » pour documenter mon parcours à travers la saison des documents de Google sur mon site Web personnel/Medium ou le blog Medium de Bokeh. Cela servira également de base pour le rapport de projet pour Google. Je vais faire 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 d'association avec 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, mentors de Bokeh pour Season of Docs. Je vais participer activement aux discussions sur Bokeh et me familiariser davantage avec Bokeh en créant et en publiant des visualisations.

Phase d'association avec la communauté (du 17 août au 13 septembre):

• Apprendre à connaître l'équipe de base, affiner le plan du projet en échange avec des mentors
• Définissez un calendrier et des canaux de communication pour la création de rapports et l’échange de commentaires réguliers avec les mentors.
• Soyez actif sur le Slack de Bokeh pour informer tous les contributeurs Bokeh intéressés de la Season of Docs de Google et des objectifs de la phase de développement de documents.
• Recueillir les commentaires des contributeurs Bokeh pour affiner davantage le plan de la phase de développement du document

Phase de développement du document

Semaine 1, 14/09 – 20/09:

• Commencer à auditer et à modifier la documentation narrative
• Commencer à élaborer des directives de style

Semaine 2, 21/09 – 27/09:

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

Semaine 3, 28/09 – 04/10:

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

Semaine 4, 05/10 – 11/10:

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

Semaine 5, 12/10 – 18/10:

• Organisez une session de questions/réponses avec des contributeurs Bokeh sur Slack pour discuter des directives de style, des améliorations à apporter à la documentation narrative et des flux de travail PR/CI.
• Commencer à développer une démonstration de faisabilité pour les métadonnées OpenGraph dans une extension Sphinx déployable
• Modifier les consignes de style en fonction des commentaires recueillis lors de la séance de questions-réponses avec les contributeurs Bokeh

Semaine 6, 19/10 – 25/10:

• Commencer à tester les outils de contrôle qualité des documents dans les workflows de relations publiques 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 des contributeurs Bokeh sur Slack
• Réviser les produits livrables en fonction du feedback de la deuxième session de questions-réponses

Semaine 8, 11/02 – 08/11:

• Déployer l'extension Sphinx et publier une documentation narrative améliorée et une page de destination pour la documentation

Semaine 9, 09/11 – 15/11:

• Déployer des outils de contrôle qualité des documents dans les workflows des relations publiques et CI
• Mettre à jour et publier le guide du développeur pour y inclure des consignes de style et des ajouts aux flux de travail des relations publiques et CI

Semaine 10, 16/11 – 22/11:

• Finaliser les tâches restantes

Semaine 11, 23/11 – 29/11:

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

Phase de finalisation du projet

Semaine 12, 30/11 – 05/12:

• Finaliser et soumettre le rapport du projet

Semaine 13, 12/03 – 10/12:

• Finaliser et soumettre l’évaluation du projet

Au terme de la "Season of Docs" de Google:

• J'espère rester impliqué dans le développement de Bokeh et continuer à travailler sur la documentation de Bokeh.
• Je prévois de poursuivre le développement d'une extension Sphinx pour les métadonnées OpenGraph/Structured Data.
• J'espère mettre à profit mon expérience en journalisme et mon réseau existant pour promouvoir Bokeh en tant qu'outil dans le journalisme de données. Par exemple, vous pouvez parler de Bokeh en pensant à un public journalistique ou en organisant des conférences sur l'utilisation de Bokeh dans un contexte journalistique.

6. À propos de moi

Je suis à l'origine journaliste, et j'ai fait de l'actualité télévisuelle, radiophonique et en ligne. Travailler en tant que rédactrice en chef et journaliste dans le secteur de la télévision et de l'actualité numérique m'a permis d'avoir des années d'expérience dans l'écriture et le montage. Parallèlement, j'ai travaillé sur plusieurs projets promouvant la transformation numérique et 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 les marques d'actualités numériques. J'ai également formé des membres de l'équipe à l'utilisation de ces outils.

J'ai toujours été attirée par les intersections entre la communication et la technologie. Un tout nouveau monde s'est ouvert lorsque j'ai appris à coder en Python: j'ai pu effectuer l'analyse et la visualisation 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 des salles de rédaction.

Les manuels et les documents que j'ai rédigés lors de mon travail précédent sont malheureusement privés. Par conséquent, je me concentre désormais sur le fait de m'impliquer davantage dans les projets Open Source (voir des exemples ci-dessous). Mon travail de rédaction technique s'appuie sur des guides de style tels que le guide de style Google pour les développeurs et le guide de style Microsoft. J'utilise régulièrement GitHub, Slack et Linux. J'ai écrit des documentations narratives, des docstrings et des indices de saisie à l'aide d'outils comme Sphinx, Mypy et Sphinx Autodoc.

Je travaille actuellement en indépendant. Mon emploi du temps offre la flexibilité nécessaire pour travailler sur la documentation de Bokeh pendant environ 25 heures par semaine pendant la phase de développement des documents. Je travaille dans le fuseau horaire du Pacifique, mais je suis ravi de pouvoir répondre aux besoins et aux plannings de l'équipe.

7. Exemples récents de documentation Open Source

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

• PyPresseportal: PyPresseportal est un wrapper Python pour l'API du site Web pressportal.de. Le site Web pressportal.de est l'un des plus grands distributeurs de communiqués de presse et d'annonces sur les relations avec les investisseurs en Allemagne. Ainsi, la plupart des services de police et de pompiers utilisent ce service pour diffuser 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 nombreuses ressources de données du site Web en tant qu'objets Python. J'ai écrit le code et l'intégralité de la documentation basée sur Sphinx.