Progetto Rocket.Chat

Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.

Riepilogo del progetto

Organizzazione open source:

Rocket.Chat

Redattore tecnico:

Mister Gold

Nome progetto:

Documenti sul bot

Durata del progetto:

Durata standard (3 mesi)

Project description

RIEPILOGO DEL PROGETTO

I bot di chat sono all'avanguardia della tecnologia di oggi. I tassi di crescita complessivi elevati di software e bot di chat, insieme all'aumento del riconoscimento vocale e dell'automazione, impongono la necessità di creare una documentazione dei bot facile da comprendere e utilizzare.

Avere una documentazione completa e chiara diventa ancora più importante, quindi la documentazione esistente dei bot deve essere semplificata e deve essere più facile da consultare, deve fornire istruzioni dettagliate unificate per ogni framework supportato ed esempi esaustivi. Inoltre, devono essere ordinate per eliminare le informazioni ridondanti e difficili da comprendere.

L'obiettivo del progetto è colmare il divario di conoscenze e incoraggiare nuovi sviluppatori meno esperti a offrire i vantaggi di una tecnologia all'avanguardia a un pubblico entusiasta. Questo può essere fatto offrendo ai creator di bot un'esperienza semplificata per lo sviluppo dei propri bot in Rocket.Chat. L'obiettivo è rendere Rocket.Chat la piattaforma open source preferita da questi sviluppatori per innovare, creare e testare le loro idee per i chatbot, indipendentemente dal target di deployment finale del BOT.

Problemi relativi ai progetti

Di seguito è riportato un elenco dei problemi più importanti relativi alla documentazione dei bot:

1. Informazioni generali poco intuitive sui bot
2. Sezioni sparse e ridondanti relative all'architettura dei bot
3. Istruzioni disorganizzate della guida "Per iniziare" senza un'unica fonte attendibile
4. Mancanza di istruzioni o un livello eccessivo di dettagli delle istruzioni
5. Documentazione vaga e implicita dell'SDK Bot

PROPOSTA DI PROGETTO

In base all'obiettivo del progetto e ai problemi sopra descritti, di seguito è riportato un elenco dei miglioramenti proposti:

1. Aggiorna la documentazione del bot. Per rendere l'introduzione iniziale fluida e coerente, i seguenti documenti devono essere aggiornati in modo graduale da semplice a più complesso:

   • Panoramica dei bot: https://rocket.chat/docs/bots/
   • Architettura dei bot: https://rocket.chat/docs/bots/bots-architecture/
   • Configurazione di ambienti bot: https://rocket.chat/docs/bots/configure-bot-environment/
   • Home page dei bot: https://github.com/RocketChat/rocketchat.github.io/pull/

2. Organizzare e unificare la documentazione di installazione dei bot. Tutti i progetti secondari devono avere un set unificato di istruzioni su come clonare un repository di bot e installare le dipendenze richieste, come iniziare rapidamente, come utilizzare un bot dopo il primo avvio e come eseguirne il deployment.

3. Rivedi la presentazione della documentazione dell'SDK JS di Rocket.Chat. La documentazione dell'SDK deve essere generata tramite programmazione dal codice sorgente utilizzando strumenti specializzati. Questo miglioramento migliorerà la leggibilità ed eliminerà la necessità di aggiornare manualmente il documento su GitHub ogni volta che un metodo (o qualcosa al suo interno) cambia.

Cronaca

Periodo di revisione delle candidature: familiarizza con la community e le persone con cui collaborerai. Consulta le guide e le best practice per i contributi della community. Effettua i primi contributi.

Rispetto della community: esplora la community. Esamina lo stato attuale della documentazione del bot. Identifica i punti deboli.

Settimana 1: allineamento con i mentor sulla nuova visione dei bot. Crea contenuti aggiornati per la nuova home page dei bot in base alla visione.

Settimana 2: rivedi le pagine Panoramica, Architettura e Configurazione dell'ambiente dei bot

Settimana 3 - Definisci un elenco di sottoprogetti (repository GitHub del bot) da trasferire nella documentazione principale. - Definisci il funzionamento dei siti web dei bot dopo il trasferimento. - Definisci un modello che verrà utilizzato per organizzare le informazioni all'interno di questi repository. - Prepara la documentazione principale per il trasferimento

Settimana 4: trasferimento del repository bBot. Organizza le informazioni in base al modello definito

Settimana 5: trasferimento del repository Hubot. Organizza le informazioni in base al modello definito

Settimana 6: trasferisci un repository Botkit. Organizzare le informazioni in base al modello definito

Settimana 7: trasferisci il repository Rasa. Organizzare le informazioni in base al modello definito

Settimana 8: Trasferisci un repository BotPress. Organizza le informazioni in base al modello definito

Settimana 9: completamento della struttura e delle pagine della documentazione principale dopo il trasferimento di tutti i sottoprogetti del bot

Settimana 10: controlla la configurazione di JSDoc. Definisci un luogo in cui archiviare gli elementi JSDoc. Inizia a documentare i metodi del driver

Settimana 11: completa la documentazione dei metodi del driver

Settimana 12: valuta i risultati

ANALISI DETTAGLIATA DEI TRAGUARDI

PERIODO DI REVISIONE DELLA DOMANDA

La prima parte del periodo sarà dedicata a controllare i canali della community e al codice sorgente, nonché a contattare le persone che si dedicano al progetto.

La seconda parte del periodo sarà dedicata al controllo della cultura dei contributi in generale, con l'esame di guide e best practice sui contributi. Sarà il momento dei primi contributi per capire come funziona il flusso.

RELAZIONI DI COMUNITÀ

Questa volta sarà dedicata a un esame più approfondito del repository della documentazione e della relativa roadmap. Sulla base di queste informazioni, sarà possibile identificare i punti deboli (ad es. parti incomplete o mancanti) che possono essere migliorati. Crea pull request (se possibile) per colmare le lacune.

SETTIMANA 1 - SETTIMANA 2

La prima settimana sarà dedicata alla comunicazione con i mentori per allinearsi alla nuova visione della documentazione relativa ai bot. Queste informazioni faranno parte dei documenti rivisti volti a fornire ai lettori una panoramica generale di cosa sia un bot e dei suoi principi di funzionamento.

La seconda settimana sarà dedicata alla creazione dei contenuti per la nuova home page di Bot in base alla visione e alla revisione delle pagine Panoramica di Bot, Architettura e Configurazione dell'ambiente.

I documenti rivisti avranno un focus più chiaro su: - Nuovi sviluppatori che vogliono creare il proprio bot - Sviluppatori di bot professionisti che vogliono progettare/codificare/testare i propri bot utilizzando una piattaforma senza costi e facile da usare o adattare i propri bot esistenti a quella piattaforma - Sviluppatori di bot professionisti con le proprie preferenze di framework che vogliono creare bot per Rocket.Chat

L'ambito del lavoro sarà il seguente:

1. Rimuovi le sezioni ridondanti. Ad esempio, le seguenti sezioni condividono informazioni sovrapposte:
   • In che modo i bot inviano e ricevono messaggi? Nella panoramica dei bot (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
   • Stream di messaggi nell'architettura dei bot (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
   • Parla con il tuo bot in Creazione di utenti bot (https://rocket.chat/docs/bots/creazione-bot-users/#talk-to-your-bot)

2. Rivedi le sezioni e le frasi della pagina Panoramica dei bot in modo che descrivano chiaramente l'ecosistema e le funzionalità dei bot in base al principio DRY.

   Rivedi le sezioni e le frasi relative alle informazioni ""sotto il cofano"":

   • Che cos'è un bot dal punto di vista tecnico
   • Quali componenti sono inclusi
   • Come interagiscono questi componenti

3. Scrivi una guida rapida che descriva i passaggi necessari per creare un bot (con un link a ""Configurazione degli ambienti dei bot"" come lettura di approfondimento). Questa guida si trova nella pagina Configurazione dell'ambiente.

In questo modo, uno sviluppatore avrà una visione chiara della natura dei bot e di ciò che questi sono in grado di fare. A questo punto, uno sviluppatore potrà creare il suo primo bot.

Risultati: guide introduttive riviste e facili da seguire con informazioni sull'ecosistema e sull'architettura dei bot.

SETTIMANA 3 - 9

Le settimane dalla 3 alla 9 saranno dedicate all'unificazione di tutti i documenti bot nei repository GitHub e al trasferimento di questi documenti nella documentazione principale (https://rocket.chat/docs/bots/). Queste attività possono essere suddivise in più iterazioni:

1. Definizione

   Definizione di un elenco di sottoprogetti di bot di cui deve essere eseguita la migrazione alla documentazione principale. Definisci il funzionamento dei siti web dei bot dopo il trasferimento (ad esempio, alcuni bot, come bbot (http://bbot.chat), hanno siti separati con documentazione oltre a GitHub).

2. Modello

   Definire e creare un modello (un modo) per organizzare le informazioni all'interno dei sottoprogetti del bot definiti nel primo passaggio. Questo modello potrebbe avere il seguente aspetto:

   a. Clonare un repository

   b. Installa le dipendenze

   c. Configurare un bot

   d. Eseguire un bot

   e. Configurazione avanzata

   f. Ulteriori passaggi

   I comandi che includono un output non banale (ad esempio ""esegui un bot"") devono essere accompagnati da presentazioni in tempo reale dell'output utilizzando lo strumento Term Sheets (https://neatsoftware.github.io/term-sheets/).

   Inoltre, per chiarire la fase iniziale di ""avvio rapido"" (passaggi da A a D), tutti i passaggi verranno combinati in una presentazione dal vivo.

   Affinché i nuovi arrivati si sentano al sicuro da potenziali errori, è necessario fornire esempi di codice nell'ambiente del parco giochi (utilizzando Glitch, come parte dell'ecosistema di Rocket Chat), in cui i nuovi arrivati possono chattare con bot che contengono il ""codice di esempio"" dietro le quinte.

3. Preparazione

   Preparazione della documentazione principale per un trasferimento. Sono incluse la creazione della struttura corretta di cartelle e pagine, nonché la modifica del sommario in base a questa struttura.

   La struttura finale potrebbe avere il seguente aspetto:

   • Bot
     • Architettura dei bot
     • Crea utenti bot
     • Configura l'ambiente del bot
     • Esegui bot
       • Bot bBot
       • Bot Hubot
       • Bot di Botkit
       • Bot Rasa
       • Bot Botpress

4. Migrazione

   Migrazione dei sottoprogetti di bot definiti alla documentazione principale uno alla volta. Ogni parte della documentazione del bot avrà una pagina separata con sottosezioni come la versione corrente (ad es. l'esecuzione di un bBot).

   • Esegui bot
     • Bot bBot
     • Bot Hubot
     • Bot di Botkit
     • Bot Rasa
     • Bot Botpress

5. Organizzazione

   Saranno disponibili diverse attività:

   1. Organizzazione delle informazioni di ogni repository GitHub del bot in base al modello definito nel secondo passaggio.
   2. Spostamento di componenti comuni (ad es. variabili di ambiente) correlati a tutti i sottoprogetti di bot di un livello superiore nella gerarchia della documentazione principale e collegamento di sottoprogetti di bot a questi componenti
   3. Creazione di un bot "hello world" di esempio per ogni framework supportato. Questo esempio verrà utilizzato come bot di "iniziazione" per Rocket.Chat.

Perché è importante? Tutti gli 8 sottoprogetti supportati da Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy hanno documenti sparsi sotto forma di README per gli sviluppatori. Questi file README non hanno alcuna struttura, contengono informazioni obsolete su come iniziare o contengono troppe informazioni (a volte con tripla ridondanza, come hubot (https://github.com/RocketChat/hubot-rocketchat) su come eseguire un bot utilizzando Docker), nonché la tabella contenente le variabili di ambiente.

Questi aspetti confondono uno sviluppatore (come utente nuovo) con l'enorme livello di dettaglio. Di conseguenza, lo sviluppatore non riuscirà a rendere operativo un bot con pochi comandi del terminale.

Al termine del trasferimento e dell'ottimizzazione, i repository dei bot esistenti su GitHub avranno file README che fanno riferimento alla documentazione principale.

Ciò offrirà i seguenti vantaggi: - Una struttura unificata che semplifica l'utilizzo dei nuovi bot da parte degli sviluppatori - Un'unica fonte attendibile per la documentazione dei bot - Ricerca più facile delle informazioni necessarie su qualsiasi bot grazie alla struttura unificata

Materiali da produrre: organizzati in un unico posto (documentazione principale) istruzioni facili da seguire su come creare, configurare ed eseguire i bot supportati da Rocket.Chat.

SETTIMANA 10

Questa settimana sarà dedicata alla configurazione di JSDoc (https://devdocs.io/jsdoc/) per massimizzare il valore dei commenti in linea. È incluso quanto segue:

1. Assicurarsi che JSDoc sia configurato correttamente per analizzare i commenti per i metodi driver (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
2. Installa postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) per rendere l'output HTML risultante più esplicito e adatto agli sviluppatori
3. Definire la posizione in cui verranno pubblicati gli elementi della documentazione JSDoc
4. Descrivere tutte le funzioni (in dist/lib/driver.js) relative ai metodi del driver. Ad esempio:
   • Aggiunta/modifica delle descrizioni dei metodi
   • Aggiunta/modifica delle descrizioni dei parametri del metodo
   • Aggiunta/modifica di esempi di richieste di metodi, se applicabile
   • Aggiunta/modifica di esempi di risposte del metodo, se applicabile

La documentazione in linea è più facile da scrivere e gestire dal punto di vista dello sviluppatore e il suo meccanismo di generazione automatica ti consente di eliminare la documentazione statica ospitata su GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) che deve essere aggiornata separatamente a ogni modifica dei metodi SDK.

SETTIMANA 11

Questa settimana sarà interamente dedicata a finalizzare la descrizione dei metodi dei conducenti. Al termine, le descrizioni verranno testate per verificarne l'accuratezza e la coerenza, dopodiché la nuova documentazione verrà pubblicata a livello mondiale.

SETTIMANA 12

Finalizzazione del lavoro completato. Controlli di accettazione.