Projet Rocket.Chat

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:

Rocket.Chat

Rédacteur technique:

Mister Gold

Nom du projet:

Documentation sur les bots

Durée du projet:

Durée standard (3 mois)

Project description

RÉSUMÉ DU PROJET

Les chatbots sont à la pointe de la technologie actuelle. Les taux de croissance globaux énormes des logiciels de chat et des bots, ainsi que la reconnaissance vocale et l'automatisation en plein essor, imposent la création de documentations de bot faciles à comprendre et à utiliser.

Il est de plus en plus essentiel de disposer d'une documentation complète et claire. Il est donc nécessaire de faciliter l'accès à la documentation existante sur les bots et la navigation, et de fournir des instructions détaillées et unifiées pour chaque framework compatible, ainsi que des exemples complets. Il doit également être nettoyé pour supprimer 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 à offrir les avantages de la technologie de pointe à une audience enthousiaste. Pour ce faire, nous devons fournir aux créateurs de bots une expérience simplifiée pour développer leurs propres bots dans Rocket.Chat. L'objectif est de faire de Rocket.Chat la plate-forme Open Source préférée de ces développeurs pour innover, créer et tester leurs idées de chatbot, quelle que soit la cible de déploiement finale du bot.

Problèmes liés au projet

Vous trouverez ci-dessous la liste des problèmes les plus importants liés à la documentation sur les bots:

1. Informations générales peu intuitives et peu conviviales sur les bots
2. Sections dispersées et redondantes concernant l'architecture des bots
3. Des instructions désorganisées du guide de démarrage sans source unique de vérité
4. Manque d'instructions ou niveau excessif d'instructions
5. Documentation implicite et vague du SDK Bot

PROPOSITION DE PROJET

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

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

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

2. Organiser et unifier la documentation d'installation des bots Tous les sous-projets doivent disposer d'un ensemble unifié d'instructions expliquant comment cloner un dépôt de bots 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. Réviser la présentation de la documentation du SDK JS Rocket.Chat. La documentation du SDK doit être générée de manière programmatique à partir du code source, à l'aide d'outils spécialisés. Cette amélioration rend le document plus lisible et évite d'avoir à mettre à jour manuellement le document sur GitHub chaque fois qu'une méthode (ou un élément qu'il contient) est modifiée.

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 et les bonnes pratiques concernant les contributions à la communauté. Apportez les premières contributions.

Liens communautaires: explorez la communauté. Inspectez l'état actuel de la documentation sur les bots. Identifiez les points faibles.

Semaine 1: Familiarisez-vous avec la nouvelle vision des bots avec vos mentors. Créer un contenu actualisé pour la nouvelle page d'accueil des bots conformément à notre vision.

Semaine 2: Réviser les pages "Présentation des bots", "Architecture" et "Configuration de l'environnement"

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

Semaine 4: transférez le dépôt bBot. Organiser les informations en fonction du modèle défini

Semaine 5: Transfert du dépôt Hubot. Organiser les informations en fonction du modèle défini

Semaine 6: transférer le dépôt Botkit Organiser les informations en fonction du modèle défini

Semaine 7: Transférez le dépôt Rasa. Organiser les informations en fonction du modèle défini

Semaine 8: transférez le dépôt BotPress. Organiser les informations en fonction du modèle défini

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

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

Semaine 11: Finaliser la documentation des méthodes du pilote

Semaine 12: Évaluer les résultats

RÉPARTITION DÉTAILLÉE DES ÉTAPES

PÉRIODE D'EXAMEN DES CANDIDATURES

La première partie sera consacrée à la vérification des canaux de la communauté et du code source, et à contacter les personnes qui se consacrent au projet.

La deuxième partie de la période sera consacrée à l'examen de la culture de contribution en général, en examinant les guides et les bonnes pratiques de contribution. C'est à ce moment-là que les premières contributions expliquent le fonctionnement du flux.

COLLECTION DE 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, les parties 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 s'aligner sur la nouvelle vision de la documentation sur les bots. Ces informations feront partie des documents révisés visant à donner aux lecteurs un aperçu général de ce qu'est un bot et de ses principes de travail.

La deuxième semaine consistera à créer du contenu pour la nouvelle page d'accueil des bots en fonction de la vision et à réviser les pages "Présentation des bots", "Architecture" et "Configuration de l'environnement".

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

Le champ d'application des travaux sera le suivant:

1. Supprimez les sections redondantes. Par exemple, les sections suivantes partagent des informations qui se chevauchent :
   • Comment les bots envoient-ils et reçoivent-ils des messages ? Dans la 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éer des utilisateurs de bot" (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot).

2. Revoyez les sections et les expressions de la page de présentation des bots pour qu'elles décrivent clairement l'écosystème et les fonctionnalités des bots selon le principe DRY.

   Révisez les sections et les expressions traitant des informations "sous le capot" :

   • Qu'est-ce qu'un bot d'un point de vue technique ?
   • Les composants dont elle se compose
   • Comment ces composants interagissent-ils ?

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

Ainsi, un développeur aura une vision claire de la nature des bots et de ce qu'ils sont capables de faire. À partir de là, un développeur pourra créer son premier bot.

Livrables: Guides d'introduction révisés et faciles à suivre, avec des informations sur l'écosystème et l'architecture des bots.

SEMAINE 3 à 9

Les semaines 3 à 9 seront consacrées à l'unification de tous les documents de robots hébergés dans les dépôts GitHub et au transfert de ces documents 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 bots à migrer vers la documentation principale Définissez le fonctionnement des sites Web des bots après le transfert (certains bots, comme bbot (http://bbot.chat), disposent de sites distincts avec de la documentation en plus de GitHub).

2. Modèle

   Définir et créer un modèle (un moyen) pour organiser les informations dans les sous-projets du 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. Étapes supplémentaires

   Les commandes qui incluent une sortie non triviale (comme ""exécuter un robot"") doivent être accompagnées de présentations en direct de cette sortie à l'aide de l'outil Term Sheets (https://neatsoftware.github.io/term-sheets/).

   De plus, pour clarifier la phase initiale de ""démarrage rapide"" (étapes a à d), toutes les étapes seront également combinées dans une présentation en direct.

   Pour que les nouveaux utilisateurs se sentent à l'abri des défaillances potentielles, des exemples de code doivent être fournis dans l'environnement de simulation (en utilisant Glitch, qui fait partie de l'écosystème Rocket Chat), afin qu'ils puissent discuter avec des bots qui disposent du "code d'exemple" en arrière-plan.

3. Préparation

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

   La structure finale peut se présenter comme suit:

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

4. Migration

   Migrer les sous-projets de bot définis vers la documentation principale, un par un. Chaque élément de la documentation du bot est associé à une page distincte avec des sous-sections telles que la version actuelle (par exemple, exécuter un bBot).

   • Exécuter des bots
     • Bot bBot
     • Hubot Bot
     • Bot Botkit
     • Rasa Bot
     • Bot Botpress

5. Organisation

   Plusieurs activités seront proposées:

   1. Organiser les informations de chaque dépôt GitHub de bot selon le modèle défini à l'étape 2.
   2. Déplacer les composants communs (par exemple, les variables d'environnement) associés à tous les sous-projets de bot d'un niveau 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 servira de bot de démarrage pour Rocket.Chat.

Pourquoi est-ce important ? Les huit sous-projets pris en charge par Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana et hubot-gitsy ont dispersé des documents sous la forme de fichiers README pour les développeurs. Ces fichiers README n'ont aucune structure, contiennent des informations obsolètes pour se lancer ou 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 les variables d'environnement.

Ces aspects déconcertent un développeur (en tant que débutant) par leur niveau de détail extrême. Par conséquent, le développeur ne pourra pas mettre en service un bot en quelques commandes de terminal.

Une fois le transfert et l'optimisation terminés, les dépôts de bots existants sur GitHub comporteront des fichiers README qui renverront à la documentation principale.

Cela offre les avantages suivants : - Une structure unifiée qui facilite la prise en main des nouveaux bots pour les développeurs - La documentation sur les bots d'une source unique d'informations fiables - La recherche des informations nécessaires sur un bot plus facile grâce à la structure unifiée

Livrables: instructions faciles à suivre pour créer, configurer et exécuter des bots compatibles avec Rocket.Chat, regroupées dans un seul et même endroit (documentation principale).

SEMAINE 10

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

1. Vérifier que JSDoc est correctement configuré pour analyser les commentaires des méthodes de 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 résultante plus explicite et conviviale pour les développeurs.
3. Définir l'emplacement où les artefacts de la documentation JSDoc seront publiés
4. Description de toutes les fonctions (dans le fichier dist/lib/driver.js) liées aux méthodes du pilote. Par exemple :
   • Ajouter/Modifier des descriptions de méthodes
   • Ajouter/Modifier des descriptions de paramètres de méthode
   • Ajout/modification d'exemples de requêtes de méthode, le cas échéant
   • Ajout/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 les descriptions terminées, leur exactitude et leur cohérence seront vérifiées, puis la nouvelle documentation sera publiée.

SEMAINE 12

Finalisation du travail terminé. Vérifications d'acceptation.