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éation, lecture et partage: optimisation de la documentation de Bokeh

Durée du projet:

Durée standard (3 mois)

Project description

Créer, lire, 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. Il compte une importante base d'utilisateurs (502 000 téléchargements de conda par mois et 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 soit cultivée de manière organique. Et donc, par endroits, incohérent, difficile d'accès et convolutif.

La saison des documents Google est une occasion 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 flux de travail associés sont pérennisés.

J'ai codé et documenté des projets Open Source avec Python et Sphinx (dernièrement: PyZillow et PyPresseportal). Mais ce qui fait de moi un participant unique à "Season of Docs" de Google, c'est mon expérience journalistique: j'ai travaillé dans des salles de rédaction pendant plus de 13 ans, avec de nombreuses années comme rédacteur en chef et défenseur du changement numérique. En plus de mes fonctions de journalisme, j'ai eu de plus en plus de responsabilités dans la conception et la documentation de nouveaux outils numériques et guides de style, ainsi que dans la formation du personnel de salle de rédaction.

Après avoir récemment déménagé de l'Europe aux États-Unis, j'ai décidé d'explorer de nouvelles manières de consolider mon enthousiasme pour la communication et le codage. J'ai trouvé que l'écriture technique était la combinaison optimale entre mes compétences et mes expériences en écriture et en technologie. Dans cette proposition, je vais expliquer comment je vais utiliser Season of Docs de Google pour optimiser la documentation de Bokeh: en facilitant la création et la contribution à la documentation, en simplifiant 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 des 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 plus, de nombreuses informations sont disponibles sur le forum d'assistance 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, avec des extensions telles que "autodoc" et "bokeh_autodoc" personnalisé. Tout comme la nature de la documentation cultivée de manière organique, elle présente 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 de conseils 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 gérondes et de mots peu courants à la place 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 du nom du fruit en tant que coordonnée x, la hauteur de la barre en tant que coordonnée supérieure et éventuellement la largeur ou d'autres propriétés à définir. Les phrases plus longues doivent être divisées en phrases plus courtes ou en listes à puces. Simplifier les phrases sera particulièrement utile pour les utilisateurs dyslexiques ou ceux dont la langue maternelle n'est pas l'anglais (voir le problème 10160).
• Utilisation incohérente de "vous" et de "nous", qui prête à confusion et qui détourne 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 de la même page). Certaines pages s'adressent même aux lecteurs de différentes manières, par exemple: "les utilisateurs devront peut-être installer des dépendances supplémentaires" ou "il est possible de créer des mises en page plus complexes".
• Des fautes de frappe, des mots manquants ou superflus et des erreurs grammaticales rompent le flux de lecture et nuisent à la crédibilité des informations: "Bokeh facilite la création de graphiques à barres basiques" ou Consultez la section Glyphs du guide de l'utilisateur.
• Les incohérences structurelles peuvent être frustrantes pour les lecteurs: par exemple, 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 (sans mention de la vaste bibliothèque de docstrings et de fonctions d'aide de modèle, des forums d'assistance, des démos ou du blog Medium). Il est également plus difficile pour les nouveaux utilisateurs de commencer à utiliser bokeh.

3. Buts

Pour tirer le meilleur parti de cette phase de développement des documents, qui dure 11 semaines, je vais me concentrer sur trois éléments clés:

3.1. Amélioration de la création de documents

La majeure partie de la documentation de Bokeh est rédigée par des contributeurs qui incluent des documents dans les demandes d’extraction pour les nouvelles fonctionnalités et les corrections de bugs. Bien que j'utilise 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 maintenance de la documentation: il doit être aussi facile que possible pour les contributeurs de maintenir un niveau de documentation systématiquement élevé.

Pour ce faire, j'applique deux approches:

• 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 connaissent les directives de style. Je proposerai également une formation individuelle et des séances 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 demandes d'extraction (PUR) et l'intégration continue (CI). Selon les 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 documentation de qualité 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 convivialité d'un texte sont son style et sa structure: si vous rédigez une documentation dans un style clair et cohérent, les lecteurs pourront 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 domaines, en insistant sur la convivialité pour les nouveaux utilisateurs. Cela inclura un examen approfondi de la documentation narrative, centrée sur le guide de l'utilisateur. Je vais également repenser la page de destination de la documentation pour s'adresser plus clairement 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 me concentrer sur la base des futures améliorations et des normes constamment élevées pour la documentation de Bokeh.

3.3. Améliorer le partage des documents

Le bokeh fait de plus en plus l'objet de discussions sur les plates-formes tierces. Bon nombre de ces plates-formes utilisent des métadonnées telles que l'OpenGraph de Facebook pour inclure des aperçus enrichis de 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, nous allons ajouter des métadonnées aux pages Web générées par le sphinx de Bokeh, comme indiqué dans le numéro 9792. La méthode la plus efficace consisterait à 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 afin de 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 instructions "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 principalement me concentrer 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 posera les bases de 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 Structured Data (par exemple, pour les numéros 1758 et 5208). Je vais m'assurer de travailler en étroite collaboration avec eux.

4. Livrables

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

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

De plus, 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. Dans la mesure du possible, je travaillerai de manière transparente, sous la forme de problèmes GitHub et de demandes d'extraction.

5. Chronologie

Avant la phase de cohésion 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, mentors de Bokeh pour la saison des documents de Google. Je vais rester actif dans la conversation sur le Bokeh et me familiariser davantage avec le Bokeh en créant et en publiant des visualisations.

Phase d'association avec une communauté (du 17/08 au 13/09):

• Apprendre à connaître l'équipe de base, affiner le plan du projet en échange avec des mentors
• Établissez un calendrier et des canaux de communication pour la création de rapports et l’échange 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 du document.
• 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 à rédiger les consignes 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 qualité des documents dans les workflows PR/CI

Semaine 5, 12/10 – 18/10:

• Organisez une session de questions/réponses avec les contributeurs Bokeh sur Slack pour discuter des consignes de style, des améliorations apportées à la documentation narrative et des workflows PR/CI.
• Commencer à développer ma démonstration de faisabilité existante pour les métadonnées OpenGraph en 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, 02/11 – 08/11:

• Déployez l'extension Sphinx, et publiez une documentation narrative et une page de destination améliorées.

Semaine 9, 09/11 – 15/11:

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

Semaine 10, 16/11 – 22/11:

• Finaliser les tâches restantes

Semaine 11, 23/11 – 29/11:

• Commencer à rédiger le rapport du 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

Après la fin de la saison des documentaires 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 utiliser mon expérience en journalisme et mon réseau actuel pour promouvoir Bokeh en tant qu'outil de journalisme de données. Vous pouvez par exemple rédiger un article sur Bokeh pour un public journalistique ou proposer des conférences sur l'utilisation de l'effet Bokeh dans un contexte journalistique.

6. À propos de moi

À l'origine, je suis journaliste. J'ai suivi l'actualité télévisuelle, en ligne et à la radio. Mon travail en tant que rédacteur en chef et journaliste pour la télévision et les actualités numériques m'a permis d'avoir des années d'expérience dans l'écriture et le montage. En parallèle, 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: par exemple, j'ai pu analyser et visualiser des données pour le journalisme de données. L'apprentissage du codage m'a également permis de collaborer activement avec des ingénieurs logiciels pour développer des outils numériques adaptés aux workflows des salles de rédaction.

Malheureusement, les manuels et les documents que j'ai rédigés pour mon poste précédent ne sont pas publics. Par conséquent, je m'attache maintenant à m'impliquer davantage dans les projets Open Source (voir les exemples ci-dessous). Mon travail de rédaction technique s'appuie sur des guides de style tels que le guide de style de la documentation destinée aux développeurs de Google et le guide de style Microsoft. J'utilise régulièrement GitHub, Slack et Linux. J'ai rédigé des documentations narratives, des docstrings et des indices de frappe, à l'aide d'outils tels que Sphinx, Mypy et Sphinx AutoDoc.

Je suis actuellement 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 du document. Je travaille dans le fuseau horaire du Pacifique, mais je suis en mesure de répondre aux besoins de l'équipe et aux plannings.

7. Exemples récents de documentation Open Source

• PyZillow: PyZillow est un wrapper Python pour l'API du site Web d'agences immobilières 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 presseportal.de. Le site Web presseportal.de est l'un des plus grands distributeurs de communiqués de presse et d'annonces sur les relations avec les investisseurs en Allemagne. Par exemple, 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.