Projekt Rocket.Chat

Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.

Podsumowanie projektu

Organizacja open source:
Rocket.Chat
Pisarz techniczny:
Mister Gold
Nazwa projektu:
Dokumentacja bota
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

PODSUMOWANIE PROJEKTU

Boty na czacie to najnowocześniejsza technologia. Ogromne wskaźniki ogólnego wzrostu liczby botów i oprogramowania do czatowania, a także coraz liczniejsze rozpoznawanie mowy i automatyzacja, sprawiają, że potrzebna jest dokumentacja botów, która będzie łatwa do opanowania i wykorzystania.

Kompleksowa i przejrzysta dokumentacja sprawia, że dostęp do obecnej dokumentacji botów oraz poruszanie się po niej powinna być prostsza. Powinna ona zawierać ujednolicone instrukcje krok po kroku dotyczące każdej obsługiwanej platformy oraz obszerne przykłady. Należy też uporządkować tekst, usuwając zbędne i trudne do zrozumienia informacje.

Celem projektu jest wypełnienie luki w wiedzy i zachęcenie nowych, mniej doświadczonych programistów do korzystania z zalet najnowocześniejszej technologii wśród zainteresowanych odbiorców. Można to zrobić, zapewniając twórcom botów możliwość korzystania z uproszczonego środowiska do tworzenia własnych botów w Rocket.Chat. Celem jest sprawienie, aby Rocket.Chat stał się preferowaną platformą open source dla tych deweloperów, na której będą oni mogli wprowadzać innowacje, tworzyć i testować swoje pomysły na boty – niezależnie od ostatecznego celu wdrożenia bota.

Problemy z projektem

Oto lista najważniejszych kwestii związanych z dokumentacją botów:

  1. Nieintuicyjne i nieprzyjazne informacje ogólne o botach
  2. rozproszone i nadmiarowe sekcje związane z architekturą botów.
  3. Nieuporządkowane fragmenty instrukcji dla początkujących bez jednego źródła danych
  4. brak instrukcji lub nadmierny poziom szczegółowości instrukcji;
  5. domyślna i niejasna dokumentacja Bot SDK,

PROPOZYCJA PROJEKTU

Zgodnie z celem projektu i wymienionymi wyżej problemami przedstawiamy listę proponowanych ulepszeń:

  1. Zaktualizuj dokumenty bota. Aby wprowadzić użytkowników w temat w sposób płynny i spójny, należy zaktualizować te dokumenty, stopniowo zwiększając ich złożoność:

    • Omówienie botów: https://rocket.chat/docs/bots/
    • Architektura botów: https://rocket.chat/docs/bots/bots-architecture/
    • Konfigurowanie środowisk botów: https://rocket.chat/docs/bots/configure-bot-environment/
    • Strona główna botów: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. uporządkować i ujednolicić dokumentację instalacji botów; Wszystkie projekty podrzędne powinny zawierać ujednolicony zestaw instrukcji dotyczących klonowania repozytorium bota i instalowania wymaganych zależności, szybkiego rozpoczęcia pracy, korzystania z bota po pierwszym uruchomieniu oraz jego wdrażania.

  3. Zaktualizuj prezentację dokumentacji Rocket.Chat JS SDK. Dokumentacja pakietu SDK powinna być generowana programowo z kodu źródłowego za pomocą specjalistycznych narzędzi. To ulepszenie zwiększy czytelność i wyeliminuje potrzebę ręcznego aktualizowania dokumentu w GitHubie za każdym razem, gdy zmieni się metoda (lub coś w nim).

Przebieg

Okres sprawdzania zgłoszeń: zapoznaj się ze społecznością i ludźmi, z którymi chcesz pracować. Poznaj wskazówki i sprawdzone metody dotyczące tworzenia treści dla społeczności. Wnieś pierwsze zmiany.

Nawiązywanie więzi ze społecznością: poznaj społeczność. Sprawdź aktualny stan dokumentacji bota. Zidentyfikuj słabe punkty.

Tydzień 1. Porozmawiaj z mentorami o nowej wizji botów. Utwórz zaktualizowane treści na nową stronę główną botów zgodnie z wizją.

Tydzień 2. Przygotuj się do stron Omówienie botów, Architektura i Konfiguracja środowiska

Tydzień 3. - Określ listę podprojektów (repozytoriów bota na GitHubie), które należy przenieść do głównej dokumentacji. – Określ, jak strony internetowe botów powinny działać po przeniesieniu. – Zdefiniuj szablon, który będzie używany do porządkowania informacji w tych repozytoriach. – Przygotuj główną dokumentację do przeniesienia.

Tydzień 4. Przeniesienie repozytorium bBot. Uporządkowanie informacji według zdefiniowanego szablonu

Tydzień 5. Przeniesienie repozytorium Hubot. Uporządkowanie informacji według zdefiniowanego szablonu

Tydzień 6. Przesyłanie repozytorium Botkit. porządkowanie informacji według zdefiniowanego szablonu,

Tydzień 7. Przeniesienie repo Rasa. porządkowanie informacji według zdefiniowanego szablonu,

Tydzień 8. Przeniesienie repozytorium BotPress porządkowanie informacji zgodnie ze zdefiniowanym szablonem,

Tydzień 9. Finalizacja głównej struktury dokumentacji i stron po przeniesieniu wszystkich podprojektów botów

Tydzień 10. Sprawdź konfigurację JSDoc. Określ miejsce do przechowywania artefaktów JSDoc. Zacznij dokumentować metody sterownika

Tydzień 11. Ukończ dokumentowanie metod sterownika

Tydzień 12. Ocena wyników

SZCZEGÓŁOWY PRZEGLĄD ETAPÓW

OKRES SPRAWDZANIA APLIKACJI

Pierwsza część tego okresu będzie poświęcona sprawdzaniu kanałów społeczności i kodu źródłowego oraz kontaktowaniu się z osobami zaangażowanymi w projekt.

Druga część tego okresu będzie poświęcona ogólnie kulturze tworzenia treści, omówieniu przewodników i sprawdzonych metod dotyczących tworzenia treści. Wtedy będziesz mieć możliwość dodawania pierwszych treści, aby sprawdzić, jak działa proces.

BUDOWANIE WIĄZANIA Z SPOŁECZNOŚCIĄ

Ten czas zostanie przeznaczony na dokładniejszą analizę repozytorium dokumentacji wraz z harmonogramem. Na podstawie tych informacji będzie możliwe zidentyfikowanie słabych punktów (np. niekompletnych lub brakujących części), które można poprawić. Utwórz żądania pull (jeśli to możliwe), aby uzupełnić luki.

TYDZIEŃ 1 – TYDZIEŃ 2

Pierwszy tydzień będzie poświęcony komunikacji z mentorami w celu dostosowania dokumentacji botów do nowej wizji. Te informacje będą częścią poprawionych dokumentów, których celem jest ogólny opis botów i zasady ich działania.

W drugim tygodniu zajmiemy się tworzeniem treści na nową stronę główną botów zgodnie z jej wizją i modyfikowaniem stron Przegląd botów, architektury i konfiguracji środowiska.

Zrewidowane dokumenty będą bardziej skupione na: – nowych programistach, którzy chcą tworzyć własne boty; – profesjonalnych programistach botów, którzy chcą projektować, kodować i testować swoje boty za pomocą bezpłatnej i łatwej w użyciu platformy lub dostosować do niej swoje dotychczasowe boty; – profesjonalnych programistów botów, którzy mają swoje preferencje dotyczące frameworków i chcą tworzyć boty dla Rocket.Chat.

Zakres prac:

  1. Usuń zbędne sekcje. Na przykład te sekcje zawierają nakładające się informacje:
    • Jak boty wysyłają i odbierają wiadomości? W sekcji Omówienie botów (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Strumienie wiadomości w architekturze botów (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Porozmawiaj z botem w sekcji Tworzenie użytkowników bota (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot).

  2. Popraw sekcje i wyrażenia na stronie Omówienie botów, aby wyraźnie opisywały ekosystem i funkcje botów zgodnie z zasadami DRY.

    Zmień sekcje i wyrażenia dotyczące informacji „pod maską”:

    • Co to jest bot z perspektywy technicznej
    • z jakich komponentów się składa;
    • Jak te komponenty współpracują ze sobą

  3. Napisz krótki przewodnik opisujący czynności wymagane do utworzenia bota (z linkiem do artykułu „Konfigurowanie środowisk botów” jako dalszej lektury). Ten przewodnik znajdzie się na stronie Konfiguracja środowiska.

Dzięki temu deweloper będzie miał jasny obraz tego, czym są boty i co potrafią. Od tego momentu deweloper będzie mógł utworzyć swojego pierwszego bota.

Materiały do dostarczenia: poprawione i przystępne przewodniki wprowadzające zawierające informacje o ekosystemie i architekturze botów.

TYDZIEŃ 3–9

Tygodnie od 3 do 9 będą poświęcone na ujednolicenie wszystkich dokumentów botów w repozytoriach na GitHubie i przeniesienie ich do głównej dokumentacji (https://rocket.chat/docs/bots/). Te działania można podzielić na kilka iteracji:

  1. Definicja

    Zdefiniowanie listy podprojektów botów, które należy przenieść do głównej dokumentacji. Określ, jak powinny działać witryny botów po przeniesieniu (niektóre boty, np. bbot (http://bbot.chat), mają osobne witryny z dokumentacją oprócz github).

  2. Szablon

    Zdefiniowanie i utworzenie szablonu (sposób na uporządkowanie informacji w podprojektach bota zdefiniowanych w pierwszym kroku). Ten szablon może wyglądać tak:

    a. Kopiowanie repozytorium

    b. Instalowanie zależności

    c. Konfigurowanie bota

    d. Uruchamianie bota

    e. Konfiguracja zaawansowana

    f. Dalsze kroki

    Polecenia, które dają nieoczywiste wyniki (np. „uruchom bota”), powinny być zilustrowane prezentacją na żywo za pomocą narzędzia Term Sheets (https://neatsoftware.github.io/term-sheets/).

    Aby początkowy etap „Szybki start” (czyli kroki a–d) był bardziej przejrzysty, wszystkie te czynności zostaną połączone w jedną prezentację na żywo.

    Aby nowi użytkownicy poczuli się bezpiecznie przed potencjalnymi problemami, należy udostępnić przykłady kodu w środowisku zabaw (Glitch w ramach ekosystemu Rocket Chat), gdzie nowi użytkownicy mogą czatować z botami, które mają „przykładowy kod”.

  3. Przygotowanie

    Przygotowanie głównej dokumentacji przeniesienia. Obejmuje to tworzenie odpowiedniej struktury folderów i stron oraz dostosowywanie spisu treści do tej struktury.

    Ostateczna struktura może wyglądać tak:

    • Boty
      • Architektura botów
      • Tworzenie użytkowników bota
      • Konfigurowanie środowiska bota
      • Uruchamianie botów
        • bBot Bot
        • Bot Hubot
        • Bot Botkit
        • Bot Rasa
        • Botpress

  4. Migracja

    Przenoszenie zdefiniowanych podprojektów bota do głównej dokumentacji jeden po drugim. Każda część dokumentacji bota będzie mieć osobną stronę z podsekcjami, np.bieżąca wersja (np. uruchamianie bBota).

    • Uruchamianie botów
      • bBot Bot
      • Bot Hubot
      • Bot Botkit
      • Bot Rasa
      • Bot Botpress

  5. Organizacja

    Będzie kilka działań:

    1. uporządkowanie informacji z repozytorium GitHub każdego bota zgodnie z szablonem zdefiniowanym w 2. kroku;
    2. Przenoszenie wspólnych komponentów (np. zmiennych środowiskowych) powiązanych ze wszystkimi podprojektami botów o jeden poziom wyżej w hierarchii głównej dokumentacji i połączanie z nimi podprojektów botów
    3. Tworzenie przykładowego bota „hello world” na potrzeby każdej obsługiwanej platformy. Ten przykład będzie używany jako bot wprowadzający dla Rocket.Chat.

Dlaczego to takie ważne? Wszystkie 8 podprojektów obsługiwanych przez Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy mają rozproszone dokumenty w formie README dla deweloperów. Te pliki README nie mają żadnej struktury, zawierają nieaktualne informacje o tym, jak zacząć, lub zawierają za dużo informacji (czasami z potrójną nadmiarowością, np. Hubot (https://github.com/RocketChat/hubot-rocketchat) na temat uruchamiania bota za pomocą Dockera), a także tabelę ze zmiennymi środowiskowymi.

Te aspekty wprowadzają dewelopera (jako nowego użytkownika) w błąd ze względu na ogromny poziom szczegółowości. W rezultacie deweloper nie będzie w stanie uruchomić bota za pomocą kilku poleceń terminala.

Po zakończeniu przenoszenia i optymalizacji istniejące repozytoria botów w githubach będą zawierać pliki README, które odnoszą się do głównej dokumentacji.

Da to następujące korzyści: - ujednolicona struktura, która ułatwia deweloperom rozpoczęcie pracy z nowymi botami; - ujednolicone źródło dokumentacji botów; - łatwiejszy dostęp do potrzebnych informacji o dowolnym botie dzięki ujednoliconej strukturze.

Materiały: zebrane w jednym miejscu (główna dokumentacja) i łatwe do wykonania instrukcje dotyczące tworzenia, konfigurowania i uruchamiania botów obsługiwanych przez Rocket.Chat.

TYDZIEŃ 10

W tym tygodniu zajmiemy się konfiguracją JSDoc (https://devdocs.io/jsdoc/) w celu maksymalizacji wartości komentarzy w kodzie. Obejmuje to m.in.:

  1. Zapewnienie prawidłowej konfiguracji JSDoc do analizowania komentarzy w przypadku metod sterownika (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Zainstaluj postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme), aby uzyskać bardziej przejrzysty i przyjazny dla deweloperów kod HTML.
  3. określenie miejsca, w którym zostaną opublikowane artefakty dokumentacji JSDoc;
  4. Opisuje wszystkie funkcje (w pliku dist/lib/driver.js) powiązane z metodami sterownika. Dotyczy to m.in.:
    • Dodawanie i edytowanie opisów metod
    • Dodawanie i edytowanie opisów parametrów metody
    • dodawanie lub edytowanie przykładów żądań metod (w stosownych przypadkach).
    • Dodawanie lub edytowanie przykładów odpowiedzi metody (w stosownych przypadkach)

Z perspektywy programisty dokumentacja wbudowana jest łatwiejsza do napisania i utrzymania, a jej mechanizm automatycznego generowania pozwala pozbyć się statycznej dokumentacji hostowanej na GitHubie (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods), która musi być aktualizowana osobno po każdej zmianie w metodach pakietu SDK.

TYDZIEŃ 11

Ten tydzień zostanie w pełni przeznaczony na finalizację opisu metod kierowców. Gdy skończymy, opisy zostaną przetestowane pod kątem dokładności i spójności. Następnie nowa dokumentacja zostanie opublikowana na całym świecie.

TYDZIEŃ 12

Finalizacja ukończonych prac. Sprawdzanie akceptacji.