Projet Rocket.Chat

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:

Rocket.Chat

Rédacteur technique:

Monsieur Gold

Nom du projet:

La documentation du bot

Durée du projet:

Durée standard (3 mois)

Project description

RÉSUMÉ DU PROJET

Les chatbots sont à la pointe de la technologie. En raison du taux de croissance global élevé des logiciels de chat et des bots, ainsi que de la hausse de la reconnaissance vocale et de l'automatisation, il est nécessaire de créer une documentation facile à comprendre et à utiliser pour les bots.

Il est d'autant plus important de disposer d'une documentation complète et claire. C'est pourquoi la documentation existante sur les bots doit être plus facile d'accès et de navigation, et doit fournir des instructions unifiées et détaillées pour chaque framework compatible, ainsi que des exemples complets. Elles doivent également être nettoyées afin d’éliminer les informations redondantes et difficiles à comprendre.

L'objectif du projet est de combler le fossé de connaissances et d'encourager les nouveaux développeurs moins expérimentés à faire profiter un public enthousiaste des avantages des technologies de pointe. Pour cela, il est possible de proposer aux développeurs une expérience simplifiée dans le développement de leurs propres bots dans Rocket.Chat. L'objectif est de faire de Rocket.Chat la plate-forme Open Source préférée des développeurs pour innover, créer et tester leurs idées de chatbot, quelle que soit l'objectif ultime de déploiement de la BOT.

Problèmes liés au projet

Voici la liste des problèmes les plus critiques liés à la documentation sur les bots:

1. Informations générales non intuitives et peu conviviales sur les bots
2. Sections dispersées et redondantes liées à l'architecture des bots
3. Instructions désordonnées du guide de démarrage, sans source unique de référence
4. Manque d'instructions ou niveau excessif de détails sur les instructions
5. Documentation implicite et vague du SDK de bot

PROPOSITION DE PROJET

En fonction de l'objectif du projet et des problèmes décrits ci-dessus, voici une liste des améliorations proposées:

1. Mettre à jour la documentation sur les bots. Pour que l’introduction initiale soit fluide et cohérente, les documents suivants doivent être mis à jour progressivement, du plus simple au plus complexe:

   • Présentation des bots: https://rocket.chat/docs/bots/
   • Bots Architecture: https://rocket.chat/docs/bots/bots-architecture/
   • Configurer des environnements de bots: https://rocket.chat/docs/bots/configure-bot-environment/
   • Page d'accueil des bots: https://github.com/RocketChat/rocketchat.github.io/pull/

2. Organisez et unifiez la documentation sur l'installation des bots. Tous les sous-projets doivent comporter un ensemble unifié d'instructions expliquant comment cloner un dépôt de bot et installer les dépendances requises, comment démarrer rapidement, comment utiliser un bot après le premier lancement et comment le déployer.

3. Modification de la présentation de la documentation du SDK JS Rocket.Chat La documentation du SDK doit être générée de façon automatisée à partir du code source à l'aide d'outils spécialisés. Cette amélioration a pour effet d'améliorer la lisibilité et d'éviter de devoir mettre à jour manuellement le document sur GitHub chaque fois qu'une méthode (ou un élément qu'il contient) change.

Temps forts

Période d'examen des candidatures: familiarisez-vous avec la communauté et les personnes avec qui vous souhaitez travailler. Découvrez les guides pour la contribution de la communauté et les bonnes pratiques. Apportez les premières contributions.

Engagement communautaire: explorez la communauté. Inspectez l'état actuel de la documentation sur les bots. Identifier les points faibles.

Semaine 1: discutez avec les mentors de la nouvelle vision des bots. Créer un contenu actualisé pour la nouvelle page d'accueil Bots conformément à notre vision.

Semaine 2: Réviser les pages de présentation des bots, de l'architecture et de la configuration des environnements

Semaine 3 - Définissez une liste de sous-projets (dépôts GitHub de bots) à transférer dans la documentation principale. - Définissez le fonctionnement des sites Web de bots après le transfert. - Définissez un modèle qui servira à organiser les informations dans ces dépôts. - Préparer la documentation principale pour le transfert

Semaine 4: transférer le dépôt bBot. Organiser les informations selon le modèle défini

Semaine 5: transférer le dépôt Hubot. Organiser les informations selon le modèle défini

Semaine 6: transférer le dépôt Botkit. Organiser les informations selon le modèle défini

Semaine 7: Transférer le dépôt Rasa. Organiser les informations selon le modèle défini

Semaine 8: transférer le dépôt BotPress. Organiser les informations selon le modèle défini

Semaine 9: Finalisation de la structure et des pages de documentation principale après le transfert de tous les sous-projets de bot

Semaine 10: vérifier la configuration JSDoc. Définissez un emplacement pour stocker les artefacts JSDoc. Commencer à documenter les méthodes de pilote

Semaine 11: Terminer de documenter les méthodes du pilote

Semaine 12: évaluer les résultats

DÉTAILS DÉTAILLÉS DES ÉTAPES

PÉRIODE D'EXAMEN DES DEMANDES

La première partie sera consacrée à la vérification des chaînes de la communauté et du code source, ainsi qu'à la prise de contact avec les personnes dédiées au projet.

La seconde partie sera consacrée à la culture de la contribution en général, en examinant les guides de contribution et les bonnes pratiques. Ce sera l'occasion pour les premières contributions de découvrir le fonctionnement du flux.

LIENS AVEC LA COMMUNAUTÉ

Ce temps sera consacré à un examen plus approfondi du référentiel de documentation et de sa feuille de route. Sur la base de ces informations, il sera possible d’identifier les points faibles (par exemple, des pièces incomplètes ou manquantes) qui peuvent être améliorés. Créez des demandes d'extraction (si possible) pour combler les lacunes.

SEMAINE 1 – SEMAINE 2

La première semaine sera consacrée à la communication avec les mentors afin de nous aligner sur la nouvelle vision de la documentation sur les bots. Ces informations feront partie des documents révisés visant à donner aux lecteurs une vue d'ensemble de ce qu'est un bot et de ses principes de fonctionnement.

La deuxième semaine sera consacrée à la création de contenu pour la nouvelle page d'accueil des bots en fonction de la vision et à la révision des pages "Présentation des bots", "Architecture" et "Configuration de l'environnement".

Les documents révisés seront axés sur les points suivants : - Nouveaux développeurs qui souhaitent créer leur propre bot - Développeurs professionnels qui souhaitent concevoir/coder/tester leurs bots à l'aide d'une plate-forme sans frais et facile à utiliser, ou s'adapter à leurs bots existants à cette plate-forme - Développeurs de bots professionnels ayant leurs préférences de framework et souhaitant créer des bots pour Rocket.

Les travaux seront les suivants:

1. Supprimez les sections redondantes. Par exemple, les sections suivantes partagent des informations qui se chevauchent :
   • Comment les bots envoient et reçoivent-ils des messages ? Dans "Présentation des bots" (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
   • Flux de messages dans l'architecture des bots (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
   • Parlez à votre bot dans la section "Création d'utilisateurs bot" (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot).

2. Modifiez les sections et les phrases de la page de présentation des bots pour qu'elle décrive clairement l'écosystème et les fonctionnalités des bots, conformément au principe DRY.

   Modifiez les sections et les expressions relatives aux "informations avancées":

   • Définition d'un bot d'un point de vue technique
   • De quels composants il se compose
   • Comment ces composants fonctionnent-ils ensemble ?

3. Rédigez un guide de démarrage rapide décrivant les étapes nécessaires à la création d'un bot (avec un lien vers la section "Configurer des environnements de bot" pour en savoir plus). Ce guide sera placé sur la page "Configuration de l'environnement".

De cette façon, les développeurs ont une vision claire de la nature des bots et de ce qu'ils peuvent faire. Les développeurs peuvent alors créer leur premier bot.

Livrables: guides d'introduction améliorés et faciles à suivre, contenant des informations sur l'architecture et l'écosystème des bots.

SEMAINES 3 – 9

Les semaines 3 à 9 seront consacrées à l'unification de tous les documents de bots dans des dépôts GitHub et à leur transfert vers la documentation principale (https://rocket.chat/docs/bots/). Ces activités peuvent être divisées en plusieurs itérations:

1. Définition

   Définir une liste de sous-projets de bot qui doivent être migrés vers la documentation principale. Définissez le fonctionnement des sites Web des bots après le transfert (certains robots, comme bbot, par exemple (http://bbot.chat)) disposent de sites distincts avec de la documentation en plus de GitHub.

2. Template

   Définir et créer un modèle (un moyen) d'organiser les informations dans les sous-projets de bot définis à la première étape Ce modèle peut se présenter comme suit:

   a. Cloner un dépôt

   b. Installer des dépendances

   c. Configurer un bot

   d. Exécuter un bot

   e. Configuration avancée

   f. Autres étapes

   Les commandes qui contiennent des résultats complexes (comme "exécuter un bot") doivent être accompagnées de présentations en direct de ces résultats à l'aide de l'outil Feuilles de termes (https://neatsoftware.github.io/term-sheets/).

   De plus, pour clarifier l'étape initiale de « démarrage rapide » (étapes a à d), toutes les étapes seront également combinées dans une présentation en direct.

   Pour éviter d'éventuelles défaillances, des exemples de code doivent être fournis dans l'environnement de jeu (à l'aide de Glitch, qui fait partie de l'écosystème Chat de Rocket), qui permet aux nouveaux arrivants de discuter avec des bots dont le ""exemple de code"" est sous le capot.

3. Préparation

   Préparer la documentation principale pour un transfert. Cela inclut la création d'une structure de dossiers et de pages appropriée, ainsi que l'ajustement de la table des matières en fonction de cette structure.

   La structure finale peut se présenter comme suit:

   • Robots
     • Architecture des bots
     • Créer des utilisateurs bot
     • Configurer l'environnement du bot
     • Exécuter des bots
       • Bot
       • Bot Hubot
       • Botkit Bot
       • Bot rasa
       • Botpress

4. Migration

   Migrer un par un les sous-projets de bot définis vers la documentation principale. Chaque élément de la documentation sur les bots aura une page distincte avec des sous-sections comme la version actuelle (par exemple, l'exécution d'un bot).

   • Exécuter des bots
     • Bot
     • Bot Hubot
     • Botkit Bot
     • Bot rasa
     • Botpress

5. Organisation

   Plusieurs activités sont disponibles:

   1. Organiser les informations de chaque dépôt GitHub de bot en fonction du modèle défini à la deuxième étape
   2. Déplacer les composants courants (par exemple, les variables d'environnement) associés à tous les sous-projets de bots vers un niveau supérieur dans la hiérarchie de la documentation principale et associer les sous-projets de bot à ces composants
   3. Créer un exemple de bot "hello world" pour chaque framework compatible. Cet exemple sera utilisé comme bot de démarrage pour Rocket.Chat.

Pourquoi est-ce important ? Les huit sous-projets soutenus par Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana et hubot-gitsy contiennent des documents éparpillés sous la forme de fichiers README destinés aux développeurs. Ces fichiers README n'ont pas du tout de structure, contiennent des informations obsolètes sur la façon de démarrer ou contiennent trop d'informations (parfois avec une triple redondance, comme Hubot (https://github.com/RocketChat/hubot-rocketchat) sur l'exécution d'un bot à l'aide de Docker), ainsi que le tableau contenant des variables d'environnement.

Ces aspects déconcertent un développeur (en tant que débutant) par rapport à l'énorme niveau de détail. Par conséquent, le développeur ne parvient pas à mettre un bot opérationnel en se servant de quelques commandes de terminal.

Une fois le transfert et l'optimisation terminés, les dépôts de bots existants dans GitHub contiennent des fichiers README qui font référence à la documentation principale.

Vous bénéficierez des avantages suivants : - Structure unifiée qui facilite la prise en main de nouveaux bots pour les développeurs - Documentation unique et fiable pour les bots - Trouvez plus facilement les informations nécessaires sur les bots, grâce à la structure unifiée

Livrables: organisés en un seul endroit (documentation principale), avec des instructions faciles à suivre pour créer, configurer et exécuter des bots pris en charge par Rocket.Chat.

SEMAINE 10

Cette semaine, nous verrons comment configurer JSDoc (https://devdocs.io/jsdoc/) pour optimiser la valeur des commentaires intégrés. Par exemple :

1. S'assurer que JSDoc est correctement configuré pour analyser les commentaires pour les méthodes du pilote (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
2. Installez postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) pour rendre la sortie HTML générée plus explicite et plus conviviale pour les développeurs
3. Définir l'emplacement où les artefacts de la documentation JSDoc seront publiés
4. Décrire toutes les fonctions (dans dist/lib/driver.js) associées aux méthodes du pilote. Par exemple :
   • Ajouter/modifier des descriptions de méthodes
   • Ajouter/modifier des descriptions des paramètres de méthode
   • Ajouter ou modifier des exemples de requêtes de méthode, le cas échéant
   • Ajout ou modification d'exemples de réponses de méthode, le cas échéant

La documentation intégrée est plus facile à écrire et à gérer du point de vue du développeur, et son mécanisme de génération automatique vous permet de vous débarrasser de la documentation statique hébergée sur GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) qui doit être mise à jour séparément à chaque modification des méthodes du SDK.

SEMAINE 11

Cette semaine sera entièrement consacrée à la finalisation de la description des méthodes de pilote. Une fois terminées, la précision et la cohérence des descriptions sont testées, puis la nouvelle documentation est publiée.

SEMAINE 12

Finalisation du travail terminé. Contrôles d'acceptation