Rocket.Chat-Projekt

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:
Rocket.Chat
Technischer Redakteur:
Mister Gold
Projektname:
Die Bot-Dokumentation
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

PROJEKTZUSAMMENFASSUNG

Chatbots sind in der heutigen Technologie auf dem neuesten Stand. Die enormen Wachstumsraten bei Chatsoftware und Bots sowie die zunehmende Spracherkennung und Automatisierung erfordern die Erstellung einer verständlichen und nutzerfreundlichen Bot-Dokumentation.

Eine umfassende und verständliche Dokumentation wird immer wichtiger. Daher muss der Zugriff auf die vorhandene Bots-Dokumentation vereinfacht und die Navigation verbessert werden. Außerdem sollten einheitliche, detaillierte Anleitungen für jedes unterstützte Framework und umfangreiche Beispiele enthalten sein. Außerdem sollten redundante und schwer verständliche Informationen entfernt werden.

Ziel des Projekts ist es, die Wissenslücke zu schließen und neue, weniger erfahrene Entwickler zu ermutigen, die Vorteile modernster Technologie einem begeisterten Publikum zu präsentieren. Dazu müssen wir die Entwicklung eigener Bots in Rocket.Chat vereinfachen. Dieses Ziel ist es, Rocket.Chat zur bevorzugten Open-Source-Plattform zu machen, auf der diese Entwickler ihre Chatbot-Ideen innovativ entwickeln und testen können – unabhängig vom ultimativen BOT-Bereitstellungsziel.

Projektprobleme

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

  1. Allgemeine Informationen zu Bots, die nicht intuitiv und unfreundlich sind
  2. Verstreute und redundante Abschnitte im Zusammenhang mit der Bot-Architektur
  3. Unorganisierte Anleitungen für den Einstieg ohne einheitliche „Source of Truth“
  4. Fehlende Anleitungen oder zu viele Details in der Anleitung
  5. Impliziter und vage formulierter Bot SDK-Leitfaden

PROJEKTANGEBOT

Gemäß dem Ziel des Projekts und den oben beschriebenen Problemen finden Sie nachstehend eine Liste der vorgeschlagenen Verbesserungen:

  1. Aktualisieren Sie die Bot-Dokumente. Damit die Einführung reibungslos und einheitlich verläuft, sollten die folgenden Dokumente aktualisiert werden, wobei der Wechsel von einfach zu komplex schrittweise erfolgen sollte:

    • Bots – Übersicht: 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. Die Installationsdokumentation für Bots wurde neu strukturiert und vereinheitlicht. Alle Unterprojekte sollten eine einheitliche Anleitung zum Klonen eines Bot-Repositories und zum Installieren der erforderlichen Abhängigkeiten, zum schnellen Einstieg, zum Arbeiten mit einem Bot nach der ersten Einführung und zum Bereitstellen enthalten.

  3. Überarbeite die Präsentation der Dokumentation zum Rocket.Chat JS SDK. Die SDK-Dokumentation sollte programmatisch aus dem Quellcode mithilfe spezieller Tools generiert werden. Diese Verbesserung sorgt für bessere Lesbarkeit und macht es nicht mehr notwendig, das Dokument auf GitHub bei jeder Änderung einer Methode (oder etwas darin) manuell zu aktualisieren.

TICKER

Prüfzeitraum: Mach dich mit der Community und den Leuten vertraut, mit denen du zusammenarbeiten wirst. Leitfäden und Best Practices für Communitybeiträge Erstellen Sie die ersten Beiträge.

Community-Bindung: Lernen Sie die Community kennen. 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 einen aktualisierten Inhalt für die neue Bots-Startseite.

Woche 2: Seiten „Bots – Übersicht“, „Architektur“ und „Umgebungskonfiguration“ noch einmal durchgehen

Woche 3: Liste der Teilprojekte (GitHub-Repositories des Bots) definieren, die in die Hauptdokumentation übernommen werden sollen. – Definieren Sie, wie Bot-Websites nach der Übertragung funktionieren sollen. – Definieren Sie eine Vorlage, mit der Informationen in diesen Repos organisiert werden. – 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: Botkit-Repository übertragen. Informationen gemäß der definierten Vorlage organisieren

Woche 7: Rasa-Repository übertragen Informationen nach der definierten Vorlage organisieren

Woche 8: BotPress-Repository übertragen Informationen gemäß der definierten Vorlage organisieren

Woche 9: Fertigstellung der Hauptstruktur und der Seiten der Dokumentation nach der Übertragung aller Bot-Unterprojekte

Woche 10: JSDoc-Konfiguration prüfen Legen Sie einen Speicherort für JSDoc-Artefakte fest. Treibermethoden dokumentieren

Woche 11: Dokumentation der Treibermethoden abschließen

Woche 12: Ergebnisse auswerten

DETAILLIERTE MILESTONES

ZEITRAUM FÜR DIE ÜBERPRÜFUNG DER BEWERBUNG

Im ersten Teil der Zeit werden wir Community-Kanäle und den Quellcode prüfen und Personen kontaktieren, die sich mit dem Projekt auskennen.

Im zweiten Teil des Zeitraums wird die Kultur der Beiträge im Allgemeinen überprüft und es werden Leitfäden und Best Practices für Beiträge untersucht. Jetzt ist es an der Zeit, erste Beiträge zu erstellen, um zu sehen, wie der Ablauf funktioniert.

COMMUNITY BONDING

In dieser Zeit werden das Dokumentationsarchiv und seine Roadmap eingehender untersucht. Anhand dieser Informationen lassen sich Schwachstellen (z.B. unvollständige oder fehlende Teile) erkennen, die verbessert werden können. Erstellen Sie (wenn möglich) Pull-Anfragen, um die Lücken zu füllen.

WOCHE 1 - WOCHE 2

In der ersten Woche geht es um die Kommunikation mit Mentoren, um die Dokumentation zur neuen Vision für Bots zu entwickeln. Diese Informationen werden Teil der überarbeiteten Dokumente sein, die den Lesern einen allgemeinen Überblick über Bots und ihre Funktionsweise geben sollen.

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

Die überarbeiteten Dokumente werden sich stärker auf folgende Zielgruppen konzentrieren: - Neue Entwickler, die ihren eigenen Bot erstellen möchten - Professionelle [Bot]-Entwickler, die ihre Bots mit einer kostenlosen und einfach zu bedienenden Plattform entwerfen, programmieren und testen oder ihre vorhandenen Bots an diese Plattform anpassen möchten - Professionelle Bot-Entwickler mit ihren Framework-Vorlieben, die Bots für Rocket.Chat erstellen möchten

Der Arbeitsumfang sieht folgendermaßen aus:

  1. Entfernen Sie redundante Abschnitte. In den folgenden Abschnitten überschneiden sich beispielsweise Informationen:
    • Wie senden und empfangen Bots Nachrichten? In der Übersicht zu Bots (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Message Streams in der Bots-Architektur (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Unter „Bot-Nutzer erstellen“ (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot) können Sie mit Ihrem Bot chatten.

  2. Überarbeiten Sie die Abschnitte und Formulierungen auf der Seite „Bots – Übersicht“, damit das Bot-Ökosystem und die Funktionen klar beschrieben werden, gemäß dem DRY-Prinzip.

    Überarbeiten Sie Abschnitte und Formulierungen zu den Informationen „im Hintergrund“:

    • Was ein Bot aus technischer Sicht ist
    • Aus welchen Komponenten es besteht
    • So funktionieren diese Komponenten zusammen

  3. Erstellen Sie eine Kurzanleitung mit den Schritten zum Erstellen eines Bots (mit einem Link zum Artikel „Bot-Umgebungen konfigurieren“ als weiterführende Lesequelle). Dieser Leitfaden wird auf der Seite „Umgebungskonfiguration“ angezeigt.

So haben Entwickler eine klare Vorstellung von der Natur von Bots und davon, was Bots tun können. Ab diesem Zeitpunkt kann ein Entwickler seinen ersten Bot erstellen.

Lieferumfang: Überarbeitete, leicht verständliche Einführungsleitfäden mit Informationen zum Bot-System und zur Bot-Architektur.

WOCHE 3–9

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

  1. Definition

    Eine Liste der Bot-Unterprojekte definieren, die in die Hauptdokumentation migriert werden sollen. Definieren Sie, wie Bot-Websites nach der Übertragung funktionieren sollen. Einige Bots, z. B. bbot (http://bbot.chat), haben neben GitHub auch separate Websites mit Dokumentation.

  2. Vorlage

    Definition und Erstellung einer Vorlage (eine Möglichkeit), Informationen in den im ersten Schritt definierten Bot-Unterprojekten zu organisieren. 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

    Die Befehle, die nicht triviale Ausgabe enthalten (z. B. „Einen Bot ausführen“), sollten von Live-Präsentationen dieser Ausgabe mit dem Term Sheets-Tool (https://neatsoftware.github.io/term-sheets/) begleitet werden.

    Außerdem werden alle Schritte in einer Live-Präsentation zusammengefasst, um die erste Phase für den Schnelleinstieg (Schritte a–d) übersichtlicher zu gestalten.

    Damit sich Neulinge vor potenziellen Fehlern sicher fühlen, sollten in der Playground-Umgebung (mit Glitch als Teil des Rocket Chat-Ökosystems) Codebeispiele bereitgestellt werden, in denen Neulinge mit Bots chatten können, die den „Beispielcode“ im Hintergrund haben.

  3. Vorbereitung

    Die Hauptdokumentation für eine Übertragung wird vorbereitet. Dazu gehört das Erstellen der richtigen Ordner- und Seitenstruktur sowie die Anpassung des Inhaltsverzeichnisses an diese Struktur.

    Die endgültige Struktur könnte so aussehen:

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

  4. Migration

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

    • Bots ausführen
      • bBot Bot
      • Hubot-Bot
      • Botkit-Bot
      • Rasa-Bot
      • Botpress

  5. Organisation

    Es gibt mehrere Aktivitäten:

    1. Die Informationen aus jedem GitHub-Repository des Bots gemäß der im 2. Schritt definierten Vorlage organisieren
    2. Gemeinsame Komponenten (z.B. Umgebungsvariablen), die sich auf alle Bot-Unterprojekte beziehen, eine Ebene höher in der Hierarchie der Hauptdokumentation verschieben und Bot-Unterprojekte mit diesen Komponenten verknüpfen
    3. Erstellen Sie für jedes unterstützte Framework ein Beispiel für einen „Hallo-Welt“-Bot. Dieses Beispiel wird als Bot für den Einstieg in Rocket.Chat verwendet.

Warum ist das wichtig? Für alle acht von Rocket.Chat unterstützten Unterprojekte (alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy) gibt es verteilte Dokumente in Form von Entwickler-READMEs. Diese READMEs sind völlig unstrukturiert, enthalten veraltete Informationen zum Einstieg oder zu viele Informationen (manchmal mit dreifacher Redundanz, z. B. zu hubot (https://github.com/RocketChat/hubot-rocketchat) zum Ausführen eines Bots mit Docker) sowie die Tabelle mit Umgebungsvariablen.

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

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

Dies bietet folgende Vorteile: – Eine einheitliche Struktur, die Entwicklern den Einstieg in die Verwendung neuer Bots erleichtert – Single Source of Truth für die Dokumentation für Bots – Dank der einheitlichen Struktur sind die benötigten Informationen zu jedem Bot leichter zu finden.

Deliverables: An einem zentralen Ort (Hauptdokumentation) werden leicht verständliche Anleitungen zum Erstellen, Konfigurieren und Ausführen von Bots zusammengestellt, die von Rocket.Chat unterstützt werden.

WOCHE 10

Diese Woche geht es darum, JSDoc (https://devdocs.io/jsdoc/) zu konfigurieren, um den Wert von Inline-Kommentaren zu maximieren. Dazu zählen:

  1. JSDoc muss richtig konfiguriert sein, um Kommentare für Treibermethoden zu parsen (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods).
  2. Installieren Sie das Postman-JSDoc-Design (https://github.com/postmanlabs/postman-jsdoc-theme), um die resultierende HTML-Ausgabe prägnanter und entwicklungsfreundlicher zu gestalten.
  3. Festlegen, wo JSDoc-Dokumentationsartefakte veröffentlicht werden sollen
  4. Beschreibung aller Funktionen der Treibermethoden in der Datei dist/lib/driver.js Dazu zählen folgende Komponenten:
    • Methodenbeschreibungen hinzufügen/bearbeiten
    • Beschreibungen von Methodenparametern hinzufügen/bearbeiten
    • Bei Bedarf Beispiele für Methodenanfragen hinzufügen/bearbeiten
    • Falls zutreffend: Beispiele für Methodenantworten hinzufügen oder bearbeiten

Inline-Dokumentation ist aus Entwicklersicht einfacher zu schreiben und zu pflegen. Durch den automatischen Generierungsmechanismus können Sie statische Dokumentationen auf GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) loswerden, die bei jeder Änderung an den SDK-Methoden separat aktualisiert werden müssen.

WOCHE 11

Diese Woche widmen wir uns der endgültigen Beschreibung der Treibermethoden. Nach Abschluss werden die Beschreibungen auf Richtigkeit und Einheitlichkeit geprüft und die neue Dokumentation veröffentlicht.

WOCHE 12

Abschluss der abgeschlossenen Arbeit. Akzeptanzprüfungen