Rocket.Chat-Projekt

Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.

Projektzusammenfassung

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

Projektbeschreibung

PROJEKTZUSAMMENFASSUNG

Chatbots sind die fortschrittlichste Technologie der heutigen Zeit. Aufgrund der enormen Wachstumsraten bei Chat-Software und Bots sowie der zunehmenden Verbreitung von Spracherkennung und Automatisierung ist es erforderlich, eine leicht verständliche und zu verwendende Bot-Dokumentation zu erstellen.

Noch wichtiger ist eine umfassende und klare Dokumentation. Daher muss der Zugriff auf die bestehende Bot-Dokumentation und die Navigation erleichtert werden. 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, die Wissenslücke 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 in Rocket.Chat ihre eigenen Bots ganz einfach entwickeln. Ziel ist es, Rocket.Chat zur bevorzugten Open-Source-Plattform für Entwickler zu machen, auf der sie ihre Chatbot-Ideen innovativ weiterentwickeln, 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 zur Bot-Architektur
  3. Unübersichtliche Anleitung für den Startleitfaden ohne zentrale Informationsquelle
  4. Fehlende Anleitungen oder zu viele Details
  5. Dokumentation zum impliziten und vagen Bot SDK

PROJEKTVORSCHLAG

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

  1. Aktualisieren Sie die Bot-Dokumente. Damit die Einführung möglichst reibungslos und einheitlich verläuft, sollten die folgenden Dokumente schrittweise von einfach zu komplexer werden:

    • 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. Dokumentation zur Installation von Bots organisieren und vereinheitlichen Alle Unterprojekte sollten einheitliche Anweisungen zum Klonen eines Bot-Repositorys und zum Installieren der erforderlichen Abhängigkeiten haben, wie Sie schnell loslegen können, wie Sie nach dem ersten Start mit einem Bot arbeiten und wie Sie ihn bereitstellen.

  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. Durch diese Verbesserung wird die Lesbarkeit verbessert und es ist nicht mehr erforderlich, das Dokument auf GitHub jedes Mal manuell zu aktualisieren, wenn sich eine Methode (oder Elemente 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. Mach die ersten Beiträge.

Community Bonding: Die Community erkunden Prüfen Sie den aktuellen Status der Bot-Dokumentation. Identifizieren Sie Schwachstellen.

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

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

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

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 gemäß der definierten Vorlage organisieren

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

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

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

Woche 11: Dokumentation der Fahrermethoden abschließen

Woche 12: Ergebnisse auswerten

DETAILLIERTE AUFRUFE DER MEILENSTEINE

PRÜFUNGSZEITRAUM BEI ANWENDUNG

Der erste Teil der Phase ist die Überprüfung von Community-Kanälen und Quellcode sowie die Kontaktaufnahme mit Personen, die sich für das Projekt engagieren.

Im zweiten Teil des Zeitraums geht es um die allgemeine Beitragskultur und die Beitragsleitfäden und Best Practices. Dies ist der Zeitpunkt für erste Beiträge, um zu sehen, wie der User Flow funktioniert.

COMMUNITY-VERKNÜPFUNG

Diese Zeit wird einer tieferen Untersuchung des Dokumentationsarchivs und der Roadmap gewidmet. Auf Grundlage dieser Informationen können Schwachstellen (z.B. unvollständige oder fehlende Teile) identifiziert werden, die verbessert werden können. Erstellen Sie nach Möglichkeit Pull-Anfragen, um die Lücken zu schließen.

WOCHE 1 – WOCHE 2

Die erste Woche widmet sich der Kommunikation mit Mentoren, um sich auf die neue Vision für Bots vorzubereiten. Diese Informationen werden Teil der überarbeiteten Dokumente sein, die Lesern einen allgemeinen Überblick darüber geben sollen, was ein Bot ist und was seine Funktionsweise ist.

In der zweiten Woche geht es darum, Inhalte für die neue Bots-Startseite gemäß unserer 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 benutzerfreundlichen Plattform entwerfen, programmieren oder testen möchten oder die sich 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 wird wie folgt lauten:

  1. Entfernen Sie redundante Abschnitte. Die folgenden Abschnitte enthalten beispielsweise überlappende Informationen:
    • Wie senden und empfangen Bots Nachrichten? In 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)
    • Sprich mit deinem Bot unter „Bot-Nutzer erstellen“ (https://rocket.chat/docs/bots/create-bot-users/#talk-to-your-bot)

  2. Passen Sie die Abschnitte und Wortgruppen der Seite „Bots-Übersicht“ so an, dass die Bots-Umgebung und -Funktionen nach dem DRY-Prinzip klar beschrieben werden.

    Überarbeiten Sie die Abschnitte und Formulierungen zu den Informationen unter „Details“:

    • Was ist ein Bot aus technischer Sicht?
    • Aus welchen Komponenten es besteht
    • Wie diese Komponenten zusammenarbeiten

  3. Schreiben Sie eine Kurzanleitung, in der die erforderlichen Schritte zum Erstellen eines Bots beschrieben werden. Lesen Sie auch einen Link zu „Bot-Umgebungen konfigurieren“. Dieser Leitfaden wird auf der Seite „Umgebungskonfiguration“ platziert.

Auf diese Weise haben Entwickler eine klare Vorstellung von der Art von Bots und dazu, was die Bots leisten können. Danach können Entwickler ihren ersten Bot erstellen.

Liefergegenstände: Ü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

    Definieren einer Liste von Bot-Unterprojekten, die zur Hauptdokumentation migriert werden sollen. Legen Sie fest, wie Bot-Websites nach der Übertragung funktionieren sollen. Für einige Bots, z. B. http://bbot.chat, gibt es zusätzlich zu GitHub separate Websites mit Dokumentation.

  2. Vorlage

    Definieren und Erstellen einer Vorlage (eine Methode), 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 mit nicht trivialer Ausgabe (z. B. „run a bot“) sollten Live-Präsentationen dieser Ausgabe über das Term Sheets-Tool (https://neatsoftware.github.io/term-sheets/) erstellt werden.

    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 schützen können, sollte in der Spielumgebung (mithilfe von Glitch als Teil des Rocket Chat-Ökosystems) Beispiel-Codebeispiele zur Verfügung gestellt werden, in denen Neueinsteiger mit Bots chatten können, die den „Beispielcode“ kennen.

  3. Vorbereitung

    Die 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
        • Rasa-Bot
        • Botpress-Bot

  4. Migration

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

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

  5. Organisation

    Es gibt verschiedene Aktivitäten:

    1. Organisieren der Informationen aus jedem Bot-GitHub-Repository gemäß der im zweiten Schritt definierten Vorlage.
    2. Gemeinsame Komponenten (z.B. Umgebungsvariablen), die alle Bot-Unterprojekte betreffen, in der Hierarchie der Hauptdokumentation eine Ebene nach oben verschieben und Bot-Unterprojekte mit diesen Komponenten verknüpfen
    3. Erstellen eines Beispiels für den „Hello World“-Bot für jedes unterstützte Framework. Dieses Beispiel wird als Startleitfaden 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 und Hubot-gitsy haben verteilte 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 Neueinsteiger) aufgrund der enormen Detailgenauigkeit. Daher kann der Entwickler mit nur wenigen Terminalbefehlen einen Bot nicht zum Laufen bringen.

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

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

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

WOCHE 10

Diese Woche geht es um die 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. Ort festlegen, an dem JSDoc-Dokumentationsartefakte veröffentlicht werden
  4. Beschreiben aller Funktionen (in der Datei dist/lib/driver.js) im Zusammenhang mit den Treibermethoden. Dazu zählen folgende Komponenten:
    • Methodenbeschreibungen hinzufügen/bearbeiten
    • Beschreibungen von Methodenparametern hinzufügen/bearbeiten
    • Beispiele für Methodenanfragen hinzufügen/bearbeiten (falls zutreffend)
    • Beispiele für Methodenantworten hinzufügen/bearbeiten (falls zutreffend)

Die Inline-Dokumentation ist aus Sicht des Entwicklers einfacher zu schreiben und zu verwalten. Dank des automatischen Generierungsmechanismus müssen Sie auf statische Dokumentation auf GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) verzichten, die bei jeder Änderung der SDK-Methoden separat aktualisiert werden muss.

WOCHE 11

Diese Woche widmen wir uns ganz der endgültigen Beschreibung der Fahrmethoden. Anschließend werden die Beschreibungen auf ihre Genauigkeit und Einheitlichkeit getestet und die neue Dokumentation wird dann weltweit veröffentlicht.

WOCHE 12

Fertigstellung abgeschlossener Arbeiten Akzeptanzprüfungen.