Rocket.Chat-Projekt

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
Rocket.Chat
Technischer Redakteur:
Mister Gold
Projektname:
Bot-Dokumente
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

PROJEKTZUSAMMENFASSUNG

Chatbots bilden die Spitzentechnologie der heutigen Technologie. Aufgrund der hohen Gesamtwachstumsrate bei Chatsoftware und Bots sowie der zunehmenden Verbreitung von Spracherkennung und Automatisierung ist es erforderlich, eine Bot-Dokumentation zu erstellen, die leicht verständlich und zu verwenden ist.

Noch wichtiger wird es, eine umfassende und klare Dokumentation zu haben. Daher muss die bestehende Dokumentation für Bots leichter zugänglich und navigierbar sein. Außerdem sollte sie einheitliche Schritt-für-Schritt-Anleitungen für jedes unterstützte Framework sowie umfassende Beispiele enthalten. Außerdem sollte sie aufgeräumt werden, um redundante und schwer verständliche Informationen zu entfernen.

Ziel des Projekts ist es, Wissenslücken zu schließen und neue, weniger erfahrene Entwickler zu ermutigen, die Vorteile modernster Technologie einem begeisterten Publikum zugänglich zu machen. Dazu können Bot-Entwickler einfacher eigene Bots in Rocket.Chat entwickeln. Ziel ist es, Rocket.Chat zur bevorzugten Open-Source-Plattform zu machen, auf der diese Entwickler ihre Chatbot-Ideen innovativ entwickeln, entwickeln und testen können – unabhängig vom tatsächlichen Ziel der BOT-Bereitstellung.

Projektprobleme

Im Folgenden finden Sie eine Liste der wichtigsten Probleme im Zusammenhang mit der Bots-Dokumentation:

  1. Nicht intuitive und unfreundliche allgemeine Informationen zu Bots
  2. Verteilte und redundante Abschnitte im Zusammenhang mit der Bots-Architektur
  3. Unorganisierte Anleitungen im Startleitfaden ohne Single Source of Truth
  4. Fehlende Anleitungen oder zu viele Details
  5. Dokumentation zum impliziten und vagen Bot SDK

PROPOSAL

Entsprechend dem Projektziel und den oben beschriebenen Problemen finden Sie hier eine Liste der vorgeschlagenen Verbesserungen:

  1. Bot-Dokumente aktualisieren. Damit die anfängliche Einführung reibungslos und einheitlich ist, sollten die folgenden Dokumente schrittweise von „einfach“ zu „komplexer“ geändert werden:

    • Übersicht über Bots: https://rocket.chat/docs/bots/
    • Bots-Architektur: https://rocket.chat/docs/bots/bots-architecture/
    • Bot-Umgebungen konfigurieren: https://rocket.chat/docs/bots/configure-bot-environment/
    • Bots-Startseite: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Dokumentation zur Installation von Bots organisieren und vereinheitlichen. Alle Unterprojekte sollten einheitliche Anleitungen enthalten, wie ein Bot-Repository geklont und die erforderlichen Abhängigkeiten installiert werden, wie Sie schnell loslegen können, wie Sie nach dem ersten Start mit einem Bot arbeiten und wie es bereitgestellt wird.

  3. Präsentation der Dokumentation zum Rocket.Chat JS SDK überarbeiten. Die SDK-Dokumentation sollte mithilfe von speziellen Tools programmatisch aus dem Quellcode generiert werden. Diese Verbesserung verbessert die Lesbarkeit und macht es überflüssig, das Dokument auf GitHub jedes Mal manuell zu aktualisieren, wenn sich eine Methode (oder etwas darin) ändert.

TICKER

Überprüfungszeitraum der Bewerbung: Machen Sie sich mit der Community und den Personen, mit denen Sie zusammenarbeiten können, vertraut. Hier findest du Leitfäden und Best Practices für Beiträge aus der Community. Erstelle die ersten Beiträge.

Verbundenheit mit der Gemeinschaft: Erkunde die Community. Prüfen Sie den aktuellen Status der Bot-Dokumentation. Schwachstellen identifizieren

Woche 1: Mit Mentoren über die neue Vision von Bots sprechen. Erstelle entsprechend der Vision aktualisierte Inhalte für die neue Bots-Startseite.

Woche 2: Die Seiten „Bots“ überarbeiten, „Architektur“ und „Umgebungskonfiguration“

Woche 3: Definieren Sie eine Liste von Unterprojekten (Bot-GitHub-Repositories), die in die Hauptdokumentation übertragen werden sollen. – Definieren, wie Bot-Websites nach der Übertragung funktionieren sollen - Definieren Sie eine Vorlage, die zum Organisieren der Informationen in diesen Repositories verwendet wird. - Hauptdokumentation für die Übertragung vorbereiten

Woche 4: bBot-Repository übertragen. Informationen gemäß der definierten Vorlage organisieren

Woche 5: Hubot-Repository übertragen. Informationen gemäß der definierten Vorlage organisieren

Woche 6: Transfer Botkit-Repository. Informationen gemäß der definierten Vorlage organisieren

Woche 7: Rasa-Repository übertragen. Informationen gemäß der definierten Vorlage organisieren

Woche 8: Transfer BotPress-Repository. Informationen gemäß der definierten Vorlage organisieren

Woche 9: Fertigstellung der Hauptdokumentationsstruktur und -seiten nach der Übertragung aller Bot-Unterprojekte

Woche 10: JSDoc-Konfiguration überprüfen Legen Sie einen Ort zum Speichern von JSDoc-Artefakten fest. Dokumentieren der Treibermethoden beginnen

Woche 11: Dokumentieren der Treibermethoden abschließen

Woche 12: Ergebnisse auswerten

DETAILLIERTE AUFNAHME DER MEILENSTEINE

ÜBERPRÜFUNGSZEITRAUM BEI BEWERBUNG

Der erste Teil des Zeitraums widmet sich der Überprüfung von Community-Kanälen und Quellcode sowie der Kontaktaufnahme mit Personen, die sich um das Projekt kümmern.

Im zweiten Teil des Zeitraums widmen wir uns der allgemeinen Überprüfung der Beitragskultur sowie der Beitragsleitfäden und Best Practices. Dies ist der Zeitpunkt der ersten Beiträge, um zu sehen, wie der Ablauf funktioniert.

COMMUNITY-VERBINDUNG

In dieser Zeit wird das Dokumentationsarchiv und die zugehörige Roadmap eingehender untersucht. Anhand dieser Informationen lassen sich Schwachstellen (z.B. unvollständige oder fehlende Teile) identifizieren, die verbessert werden können. Erstellen Sie nach Möglichkeit Pull-Anfragen, um die Lücken zu füllen.

WOCHE 1 - WOCHE 2

Die erste Woche wird der Kommunikation mit Mentoren gewidmet, um sich auf die Dokumentation für die neue Vision für Bots zu konzentrieren. Diese Informationen werden Teil der überarbeiteten Dokumente, die Lesern einen allgemeinen Überblick über Bot und ihre Funktionsweise geben sollen.

In der zweiten Woche geht es darum, Inhalte für die neue Bots-Startseite gemäß der Vision zu erstellen und die Seiten „Bots – Übersicht“, „Architektur“ und „Umgebungskonfiguration“ zu überarbeiten.

Die überarbeiteten Dokumente haben einen klaren Fokus auf: - Neue Entwickler, die ihren eigenen Bot erstellen möchten - Professionelle [Bot]-Entwickler, die ihre Bots mithilfe einer kostenlosen und nutzerfreundlichen Plattform entwerfen/programmieren/testen oder an ihre vorhandenen Bots an diese Plattform anpassen möchten - Professionelle Bot-Entwickler mit ihren Framework-Präferenzen, die Bots für Rocket erstellen möchten.Chat

Der Arbeitsumfang umfasst Folgendes:

  1. Entfernen Sie redundante Abschnitte. Die folgenden Abschnitte enthalten beispielsweise überlappende Informationen:
    • Wie senden und empfangen Bots Nachrichten? In der Bots-Übersicht (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Nachrichtenstreams in der Bots-Architektur (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Sprechen Sie unter „Bot-Nutzer erstellen“ mit Ihrem Bot (https://rocket.chat/docs/bots/create-bot-users/#talk-to-your-bot).

  2. Überarbeiten Sie die Abschnitte und Wortgruppen der Seite „Bots-Übersicht“ so, dass sie nach dem DRY-Prinzip das System und die Funktionen der Bots klar beschreibt.

    Überarbeiten Sie Abschnitte und Formulierungen zu den Informationen:

    • Was ein Bot aus technischer Sicht ist
    • Aus welchen Komponenten es besteht
    • Interaktion dieser Komponenten

  3. Schreiben Sie eine Kurzanleitung, in der Sie die Schritte zum Erstellen eines Bots beschreiben. Außerdem finden Sie dort einen Link zu „Bot-Umgebungen konfigurieren“. Diese Anleitung wird auf der Seite „Umgebungskonfiguration“ platziert.

Auf diese Weise haben Entwickler eine klare Vorstellung davon, was Bots sind und wozu sie in der Lage sind. Ab diesem Zeitpunkt kann ein Entwickler seinen ersten Bot erstellen.

Ergebnisse: Überarbeitete, leicht verständliche Einführungsleitfäden mit Informationen zur Bots-Umgebung und -Architektur.

WOCHE 3 - 9

In den Wochen 3 bis 9 werden alle Bot-Dokumente in GitHub-Repositories vereinheitlicht und in die Hauptdokumentation (https://rocket.chat/docs/bots/) übertragen. Diese Aktivitäten können in mehrere Iterationen unterteilt werden:

  1. Definition

    Eine Liste von Bot-Unterprojekten definieren, die zur Hauptdokumentation migriert werden sollen. Legen Sie fest, wie Bot-Websites nach der Übertragung funktionieren sollen. Einige Bots, z. B. bbot (http://bbot.chat), haben zusätzlich zu GitHub separate Websites mit Dokumentation.

  2. Vorlage

    Definieren und Erstellen einer Vorlage (eine Möglichkeit), um Informationen innerhalb der Bot-Unterprojekte zu organisieren, die im ersten Schritt definiert wurden. Diese Vorlage könnte so aussehen:

    a. Repository klonen

    b. Abhängigkeiten installieren

    c. Bot konfigurieren

    d. Bot ausführen

    e. Erweiterte Konfiguration

    f. Weitere Schritte

    Zu den Befehlen, die nicht triviale Ausgaben enthalten (z. B. „Einen Bot ausführen“), sollten Live-Präsentationen dieser Ausgabe mit dem Term Sheets-Tool (https://neatsoftware.github.io/term-sheets/) vorhanden sein.

    Außerdem werden alle Schritte in einer Live-Präsentation zusammengefasst, um die anfängliche Phase des „Schnelleinstiegs“ (Schritte a–d) klarer zu gestalten.

    Damit sich Neuankömmlinge vor potenziellen Ausfällen sicher fühlen, sollte Code für die Spielplatzumgebung bereitgestellt werden (mithilfe von Glitch als Teil des Rocket Chat-Ökosystems), in dem Neueinsteiger mit Bots chatten können, die den „Beispielcode“ im Hintergrund haben.

  3. Vorbereitung

    Hauptdokumentation für eine Übertragung vorbereiten. Dazu gehört das Erstellen der richtigen Ordner- und Seitenstruktur sowie das Anpassen des Inhaltsverzeichnisses entsprechend dieser Struktur.

    Die endgültige Struktur könnte so aussehen:

    • Bots
      • Bots-Architektur
      • Bot-Nutzer erstellen
      • Bot-Umgebung konfigurieren
      • Bots ausführen
        • Bot-Bot
        • Hubot-Bot
        • Botkit-Bot
        • Rasa-Bot
        • Botpresse

  4. Migration

    Die definierten Bot-Unterprojekte einzeln zur Hauptdokumentation migrieren. Jede Bot-Dokumentation hat eine separate Seite mit Unterabschnitten wie der aktuellen Version (z.B. Ausführen eines Bots).

    • Bots ausführen
      • Bot-Bot
      • Hubot-Bot
      • Botkit-Bot
      • Rasa-Bot
      • Botpresse

  5. Organisation

    Es gibt mehrere Aktivitäten:

    1. Organisation der Informationen aus jedem Bot-GitHub-Repository gemäß der im zweiten Schritt definierten Vorlage.
    2. Gemeinsame Komponenten (z.B. Umgebungsvariablen), die sich auf alle Bot-Unterprojekte beziehen, in der Hierarchie der Hauptdokumentation eine Ebene nach oben verschieben und Bot-Unterprojekte mit diesen Komponenten verknüpfen
    3. Beispiel für einen „Hello World“-Bot für jedes unterstützte Framework erstellen. Dieses Beispiel wird als „Erste Schritte“-Bot für Rocket.Chat verwendet.

Warum ist das wichtig? Alle acht Unterprojekte, die von Rocket.Chat unterstützt werden: alexa, Hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, Hubot-gitsy haben verstreute Dokumente in Form von Entwickler-Readmes. Diese Readme-Dateien haben überhaupt keine Struktur, enthalten veraltete Informationen zu den ersten Schritten oder zu viele Informationen (manchmal mit dreifacher Redundanz wie Hubot (https://github.com/RocketChat/hubot-rocketchat) über die Ausführung eines Bots mit Docker) sowie die Tabelle mit Umgebungsvariablen.

Diese Aspekte verwirren Entwickler (als Neuling) aufgrund der enormen Detailgenauigkeit. Infolgedessen kann der Entwickler einen Bot nicht mit nur wenigen Terminalbefehlen zum Laufen bringen.

Nach Abschluss der Übertragung und Optimierung enthalten die vorhandenen Bot-Repositories in GitHub Readme-Dateien, die auf die Hauptdokumentation verweisen.

Das bietet folgende Vorteile: – Einheitliche Struktur, die Entwicklern den Einstieg in neue Bots erleichtert – Eine Single Source of Truth für Bots-Dokumentation – Einfaches Auffinden der benötigten Informationen zu jedem Bot dank der einheitlichen Struktur

Liefergegenstände: an einem zentralen Ort (Hauptdokumentation) organisiert und übersichtliche Anweisungen zum Erstellen, Konfigurieren und Ausführen von Bots, die von Rocket.Chat unterstützt werden.

WOCHE 10

Diese Woche beschäftigen wir uns mit der Konfiguration von JSDoc (https://devdocs.io/jsdoc/), um den Wert von Inline-Kommentaren zu maximieren. Dazu zählen:

  1. Sicherstellen, dass JSDoc richtig zum Parsen von Kommentaren für Treibermethoden konfiguriert ist (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Installieren Sie postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme), um die resultierende HTML-Ausgabe expliziter und entwicklerfreundlicher zu gestalten
  3. Den Ort definieren, an dem Artefakte aus der JSDoc-Dokumentation veröffentlicht werden
  4. Beschreiben aller Funktionen (in der Datei dist/lib/driver.js) im Zusammenhang mit den Treibermethoden. Dazu zählen folgende Komponenten:
    • Beschreibungen von Methoden hinzufügen/bearbeiten
    • Beschreibungen von Methodenparametern hinzufügen/bearbeiten
    • Hinzufügen/Bearbeiten von Beispielen für Methodenanfragen (falls zutreffend)
    • Beispiele für Methodenantworten hinzufügen/bearbeiten (falls zutreffend)

Die Inline-Dokumentation ist aus Entwicklersicht einfacher zu schreiben und zu pflegen und ihr Mechanismus zur automatischen Generierung ermöglicht es Ihnen, die statische Dokumentation auf GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) zu entfernen, die bei jeder Änderung der SDK-Methoden separat aktualisiert werden muss.

WOCHE 11

In dieser Woche geht es um die endgültige Beschreibung der Fahrmethoden. Anschließend werden die Beschreibungen auf Genauigkeit und Einheitlichkeit getestet und die neue Dokumentation wird weltweit veröffentlicht.

WOCHE 12

Abschluss abgeschlossener Arbeiten. Akzeptanzprüfungen.