Progetto Rocket.Chat

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.

Riepilogo del progetto

Organizzazione open source:

Rocket.Chat

Technical writer:

Oro rosa

Nome progetto:

Documenti sul bot

Durata del progetto:

Durata standard (3 mesi)

Project description

RIEPILOGO DEL PROGETTO

I bot di chat sono all'avanguardia nella tecnologia odierna. Gli enormi tassi di crescita complessivi nei software e nei bot di chat, insieme al riconoscimento vocale e all'automazione in ascesa, determinano la necessità di creare una documentazione relativa ai bot che sia facile da comprendere e usare.

Avere una documentazione completa e chiara diventa ancora più fondamentale, quindi la documentazione esistente relativa ai bot deve essere semplificata da accesso e navigazione, dovrebbe fornire istruzioni unificate passo passo per ogni framework supportato ed esempi esaustivi. Inoltre, deve essere riordinata in modo da eliminare le informazioni ridondanti e difficili da comprendere.

L'obiettivo del progetto è colmare il divario di conoscenze e incoraggiare gli sviluppatori nuovi e meno esperti a offrire i vantaggi della tecnologia all'avanguardia a un pubblico entusiasta. Ciò può essere fatto fornendo agli sviluppatori di bot un'esperienza semplificata per lo sviluppo dei propri bot in Rocket.Chat. Questo obiettivo punta a rendere Rocket.Chat la piattaforma open source preferita da parte di questi sviluppatori per innovare, creare e testare le proprie idee di chatbot, indipendentemente dall'obiettivo di deployment BOT finale.

Problemi relativi al progetto

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

1. Informazioni generali non intuitive e poco amichevoli sui bot
2. Sezioni sparse e ridondanti relative all'architettura dei bot
3. Parti disorganizzate delle istruzioni della guida "per iniziare" senza un'unica fonte attendibile
4. Mancanza di istruzioni o un livello eccessivo di dettagli sull'istruzione
5. Documentazione relativa all'SDK Bot implicito e vaga

PROPOSTA DI PROGETTO

In base all'obiettivo del progetto e alle questioni sopra descritte, di seguito è riportato un elenco dei miglioramenti proposti:

1. Aggiorna i documenti del bot. Per rendere l'introduzione iniziale fluida e coerente, è necessario aggiornare i seguenti documenti con un passaggio graduale da semplice a più complesso:

   • Panoramica sui bot: https://Rock.chat/docs/bots/
   • Architettura dei bot: https://Rock.chat/docs/bots/bots-architecture/
   • Configurazione degli ambienti bot: https://Rock.chat/docs/bots/configure-bot-environment/
   • Home page Bot: https://github.com/RocketChat/Rocketchat.github.io/pull/

2. Organizzare e unificare la documentazione di installazione dei bot. Tutti i sottoprogetti devono avere un insieme unificato di istruzioni su come clonare un repository di bot e installare le dipendenze richieste, come iniziare rapidamente, come lavorare con un bot dopo il primo lancio e come eseguirne il deployment.

3. Rivedi la presentazione della documentazione dell'SDK Rocket.Chat per JS. La documentazione dell'SDK deve essere generata in modo programmatico dal codice sorgente utilizzando strumenti specializzati. Questo miglioramento darà maggiore 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 della domanda: acquisisci familiarità con la community e le persone con cui lavorare. Scopri le guide e le best practice per i contributi della community. Pubblica i primi contributi.

Legame con la community: esplora la community. Esamina lo stato attuale della documentazione del bot. Identificare i punti deboli.

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

Settimana 2: pagine Rivedi panoramica dei bot, Architettura, Configurazione dell'ambiente

Settimana 3 - Definisci un elenco di sottoprogetti (repository bot github) che devono essere trasferiti nella documentazione principale. - Definire il funzionamento dei siti web dei bot dopo il trasferimento. - Definire un modello che verrà utilizzato per organizzare le informazioni in questi repository. - Prepara la documentazione principale per il trasferimento

Settimana 4: Trasferisci il repository bBot. Organizza le informazioni in base a un modello definito

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

Settimana 6: trasferimento del repository Botkit. Organizza le informazioni in base a un modello definito

Settimana 7: trasferimento del repository Rasa. Organizza le informazioni in base a un modello definito

Settimana 8: Trasferisci BotPremi il repository. Organizza le informazioni in base a un modello definito

Settimana 9: finalizzazione della struttura e delle pagine della documentazione principali dopo il trasferimento di tutti i sottoprogetti dei bot

Settimana 10: controlla la configurazione di JSDoc. Definisci una posizione in cui archiviare gli artefatti JSDoc. Inizia a documentare i metodi del driver

Settimana 11: completa la documentazione dei metodi del conducente

Settimana 12: valuta i risultati

SINTESI DETTAGLIATA DEI TRAGUARDI

PERIODO DI REVISIONE DELLA DOMANDA

La prima parte del periodo sarà dedicata alla verifica dei canali e del codice sorgente della community, nonché al contatto con le persone dedicate al progetto.

La seconda parte del periodo sarà dedicata alla verifica della cultura della contribuzione in generale, esaminando le guide e le best practice per i contributi. Questo sarà il momento in cui i primi contributi vedranno come funziona il flusso.

UNIONE CON LA COMMUNITY

Questo periodo sarà dedicato a un esame più approfondito del repository di 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 migliorate. Crea richieste di pull (ove 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 della funzionalità di un bot e dei suoi principi di funzionamento.

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

I documenti rivisti avranno un'attenzione più chiara a: - Nuovi sviluppatori che desiderano creare un proprio bot - Sviluppatori [bot] professionisti che desiderano progettare/codificare/testare i propri bot utilizzando una piattaforma senza costi e facile da usare oppure adattarsi ai loro bot esistenti a quella piattaforma - Sviluppatori di bot professionisti con le loro preferenze di framework che vogliono creare bot per Rocket.Chat

L'ambito di 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? Panoramica sui bot (https://Rock.chat/docs/bots/#how-do-bots-send-and-receive-messages)
   • Flussi di messaggi nell'architettura dei bot (https://Rock.chat/docs/bots/bots-architecture/#message-streams)
   • Parla con il tuo bot in Creazione di utenti bot (https://Rock.chat/docs/bots/Creating-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 sezioni e frasi sulle informazioni "profonde":

   • Che cos'è un bot dal punto di vista tecnico
   • Da quali componenti è composto
   • Funzionamento insieme di questi componenti

3. Scrivi una guida rapida che descriva i passaggi necessari per creare un bot (con un link alla pagina "Configurazione degli ambienti bot" per ulteriori letture). Questa guida verrà inserita nella pagina Configurazione dell'ambiente.

In questo modo, uno sviluppatore avrà una visione chiara della natura dei bot e di cosa sono in grado di fare. A quel punto, uno sviluppatore sarà in grado di creare il suo primo bot.

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

SETTIMANA 3 - 9

Le settimane da 3 a 9 saranno dedicate all'unificazione di tutti i documenti dei bot nei repository Github e al trasferimento di questi documenti nella documentazione principale (https://Rock.chat/docs/bots/). Queste attività possono essere suddivise in diverse iterazioni:

1. Definizione

   Definizione di un elenco di sottoprogetti di bot di cui eseguire la migrazione alla documentazione principale. Definisci come dovrebbero funzionare i siti web dei bot dopo il trasferimento (alcuni bot, bbot, ad esempio (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 dei bot definiti nel primo passaggio. Questo modello può avere il seguente aspetto:

   a. Clonare un repository

   b. Installa le dipendenze

   c. Configura un bot

   d. Eseguire un bot

   e. Configurazione avanzata

   f. Ulteriori passaggi

   I comandi che includono output non banali (come ""esegui un bot"") dovrebbero essere accompagnati da presentazioni live dell'output utilizzando lo strumento Term Fogli (https://neatsoftware.github.io/term-sheets/).

   Inoltre, per rendere più chiara la fase iniziale di ""avvio rapido" (passaggi a - d), anche tutti i passaggi verranno combinati in un'unica presentazione dal vivo.

   Per fare in modo che 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"" in background.

3. preparazione

   Preparazione della documentazione principale per un trasferimento. Ciò include la creazione della cartella e la struttura della pagina appropriate, nonché la modifica del sommario in base a questa struttura.

   La struttura finale potrebbe essere la seguente:

   • Bot
     • Architettura dei bot
     • Crea utenti bot
     • Configura ambiente bot
     • Esegui bot
       • Bot Bot
       • Hubot bot
       • Bot Botkit
       • Bot rasa
       • Bot Press

4. Migrazione

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

   • Esegui bot
     • Bot Bot
     • Hubot bot
     • Bot Botkit
     • Bot rasa
     • Bot Press

5. Organizzazione

   Ci saranno diverse attività:

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

Perché è importante? Tutti e 8 i sottoprogetti supportati da Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy hanno sparsi documenti sotto forma di README di 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-Rockchat) su come eseguire un bot utilizzando Docker), nonché la tabella che contiene le variabili di ambiente.

Questi aspetti confondono lo sviluppatore (essendo un neofita) con l'enorme livello di dettaglio. Di conseguenza, lo sviluppatore non riuscirà ad attivare un bot con pochi comandi nel terminale.

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

Questo fornirà i seguenti vantaggi: - Una struttura unificata che rende più facile per gli sviluppatori iniziare a utilizzare i nuovi bot - Un'unica fonte attendibile per la documentazione relativa ai bot - È più facile trovare le informazioni necessarie su qualsiasi bot grazie alla struttura unificata

Deliverable: organizzati sotto un'unica posizione (documentazione principale) istruzioni facili da seguire su come creare, configurare ed eseguire bot supportati da Rocket.Chat.

SETTIMANA 10

Questa settimana ci occuperemo della configurazione di JSDoc (https://devdocs.io/jsdoc/) per massimizzare il valore dei commenti in linea. È incluso quanto segue:

1. Assicurati che JSDoc sia configurato correttamente per analizzare i commenti per i metodi del 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. Definizione della posizione in cui verranno pubblicati gli artefatti della documentazione JSDoc
4. Descrivere tutte le funzioni (in dist/lib/driver.js) del file relative ai metodi del driver. Ad esempio:
   • Aggiungere/modificare 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 al 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 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 nei metodi SDK.

SETTIMANA 11

Questa settimana sarà dedicata completamente alla descrizione dei metodi dei conducenti. Una volta completata l'operazione, verificheremo l'accuratezza e la coerenza delle descrizioni e poi la nuova documentazione sarà pubblicata.

SETTIMANA 12

Finalizzazione del lavoro completato. Controlli di accettazione.