Progetto Rocket.Chat

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:
Rocket.Chat
Technical writer:
Mister Oro
Nome progetto:
Documenti di The Bot
Durata del progetto:
Durata standard (3 mesi)

Project description

RIEPILOGO DEL PROGETTO

I bot di chat sono all'avanguardia nella tecnologia di oggi. L'enorme crescita complessiva dei software e dei bot di chat, insieme al riconoscimento vocale e all'automazione in aumento, impone la necessità di creare una documentazione dei bot facile da comprendere e usare.

Avere una documentazione completa e chiara diventa ancora più cruciale, quindi la documentazione esistente sui bot deve essere più facile da consultare e navigare, dovrebbe fornire istruzioni unificate passo passo per ogni framework supportato ed esempi esaustivi. Inoltre, devono essere riordinati in modo da eliminare 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 delle tecnologie all'avanguardia a un pubblico entusiasta. Ciò può essere fatto fornendo agli sviluppatori di bot un'esperienza semplificata nello sviluppo dei propri bot in Rocket.Chat. Questo obiettivo ha lo scopo di rendere Rocket.Chat la piattaforma open source preferita per consentire a questi sviluppatori di innovare, creare e testare le proprie idee per i chatbot, indipendentemente dal target 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 sui bot non intuitive e sgradevoli
  2. Sezioni sparse e ridondanti relative all'architettura dei bot
  3. Istruzioni disordinate della guida per iniziare senza un'unica fonte attendibile
  4. Mancanza di istruzioni o un livello eccessivo di dettagli di istruzioni
  5. Documentazione relativa all'SDK Bot implicito e vaga

PROPOSTA DI PROGETTO

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

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

    • Panoramica dei 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, iniziare rapidamente, 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 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 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.

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

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

Settimana 2: pagina Panoramica dei bot, Architettura, Configurazione dell'ambiente

Settimana 3 - Definisci un elenco di progetti secondari (repository bot GitHub) che devono essere trasferiti nella documentazione principale. - Definire 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 dal repository bBot. Organizzare le informazioni in base al modello definito

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

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

Settimana 7: trasferimento del repository Rasa. Organizzare le informazioni in base al modello definito

Settimana 8: Trasferimento repository BotPress. Organizzare le informazioni in base al modello definito

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

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

Settimana 11: completa la documentazione relativa ai metodi del conducente

Settimana 12: valuta i risultati

ANALISI DETTAGLIATA DELLE TRAGUARDI

PERIODO DI REVISIONE DELLE DOMANDE

La prima parte del periodo sarà dedicata a verificare i canali e il codice sorgente della community e a contattare le persone dedicate al progetto.

La seconda parte del periodo sarà dedicata alla verifica della cultura del contributo in generale, esaminando le guide ai contributi e le best practice. Questo sarà il momento dei primi contributi per vedere come funziona il flusso.

COLLEGAMENTO DELLA COMMUNITY

Questo tempo sarà dedicato a un esame più approfondito del repository della documentazione e della relativa roadmap. In base a queste informazioni, sarà possibile identificare i punti deboli (ad es. le 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 documentazione relativa alla vision per i bot. Queste informazioni faranno parte dei documenti rivisti allo scopo di offrire ai lettori una panoramica generale su cos'è un bot e sui suoi principi di funzionamento.

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

I documenti rivisti avranno un'attenzione più chiara a: - Nuovi sviluppatori che desiderano creare il proprio bot - Sviluppatori [bot] professionisti che desiderano progettare, programmare e 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 desiderano 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? Nella panoramica dei 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 per descrivere in modo chiaro l'ecosistema e le funzionalità dei bot secondo il principio DRY.

    Rivedi le sezioni e le frasi relative alle informazioni ""Roba da smanettoni":

    • Che cos'è un bot dal punto di vista tecnico
    • Componenti in cui è composto
    • Come interagiscono 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. Da quel momento, uno sviluppatore sarà in grado di 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 dei bot attraverso i repository github e al trasferimento di questi documenti nella documentazione principale (https://essen.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 nella documentazione principale. Definisci come i siti web dei bot dovrebbero funzionare 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 di bot definiti nel primo passaggio. Questo modello potrebbe avere il seguente aspetto:

    a. Clonare un repository

    b. Installa le dipendenze

    c. Configura un bot

    d. Eseguire un bot

    e. Configurazione avanzata

    f. Passaggi aggiuntivi

    I comandi che includono output non banali (come ""esegui un bot"") devono essere accompagnati da presentazioni dal vivo 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), tutti i passaggi verranno combinati in un'unica presentazione dal vivo.

    Per far sì 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 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 tale 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 di Rasa
        • Botpress

  4. Migrazione

    Migrazione dei sottoprogetti secondari definiti nella documentazione principale uno alla volta. Ogni parte della documentazione dei 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 di Rasa
      • Botpress

  5. Organizzazione

    Ci saranno diverse attività:

    1. Organizzazione delle informazioni di ogni repository GitHub di bot in base al modello definito nel secondo passaggio.
    2. Sposta i componenti comuni (ad es. le variabili ambientali) correlati a tutti i sottoprogetti di bot a un livello superiore nella gerarchia della documentazione principale e collega i 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 documenti sparsi sotto forma di file README per sviluppatori. Questi file README non hanno una struttura, contengono informazioni obsolete su come iniziare o troppe informazioni (a volte con tripla ridondanza, come l'hubot (https://github.com/RocketChat/hubot-Rockchat) su come eseguire un bot usando Docker), nonché la tabella contenente le variabili ambientali.

Questi aspetti confondono lo sviluppatore (in quanto nuovo arrivato) 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

Risultati: organizzati in un'unica posizione (documentazione principale) istruzioni facili da seguire su come creare, configurare ed eseguire 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 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 facile da usare per gli sviluppatori
  3. Definizione della posizione in cui verranno pubblicati gli elementi 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 di descrizioni dei parametri del metodo
    • Aggiunta/modifica di esempi di richieste di metodi, se applicabile
    • Aggiunta/modifica di esempi di risposte al metodo, se applicabili

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 nei metodi SDK.

SETTIMANA 11

Questa settimana sarà dedicata interamente alla fase di finalizzazione della descrizione dei metodi dei conducenti. Una volta completate, le descrizioni verranno testate per verificarne l'accuratezza e la coerenza e poi la nuova documentazione sarà pubblicata.

SETTIMANA 12

Finalizzazione del lavoro completato. Controlli di accettazione.