Projekt Rocket.Chat

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:
Rocket.Chat
Pisarz techniczny:
Mistrz Złoty
Nazwa projektu:
Dokumentacja Bota
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

PODSUMOWANIE PROJEKTU

Boty na czacie to najnowsze technologie. Ogromne ogólne tempo wzrostu popularności oprogramowania do obsługi czatu i botów, a także rozpoznawanie mowy i automatyzacja upowszechnia się, a to sprawia, że konieczne jest stworzenie łatwej do zrozumienia dokumentacji dotyczącej botów.

Opracowanie szczegółowej i przejrzystej dokumentacji staje się jeszcze ważniejsze, dlatego należy ułatwić dostęp do istniejącej dokumentacji botów i poruszać się po niej. Należy też udostępniać ujednolicone, szczegółowe instrukcje dotyczące każdej obsługiwanej platformy oraz obszerne przykłady. Trzeba też uporządkować je w taki sposób, aby pozbyć się zbędnych i trudnych do zrozumienia informacji.

Celem tego projektu jest wypełnienie luki w wiedzy i zachęcenie nowych, mniej doświadczonych programistów do wykorzystywania najnowocześniejszych technologii w zainteresowanych odbiorcach. Można to zrobić, udostępniając kreatorom botów w łatwy sposób tworzenie własnych botów w Rocket.Chat. Chcemy, aby Rocket.Chat była preferowaną platformą open source dla tych deweloperów, aby mogli wprowadzać innowacje, tworzyć i testować pomysły czatbotów – niezależnie od ostatecznych celów wdrożenia BOT.

Problemy związane z projektem

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

  1. Nieintuicyjne i nieprzyjazne ogólne informacje 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 wiarygodnych informacji
  4. Brak instrukcji lub nadmierna ilość szczegółowych instrukcji
  5. Pośrednia i niejasna dokumentacja pakietu SDK do obsługi botów

PROPOZYCJA PROJEKTU

Oto lista proponowanych ulepszeń, wiążąca się z celem projektu i problemami opisanymi powyżej:

  1. Zaktualizuj dokumenty botów. Aby wprowadzenie na początku było proste i spójne, zaktualizuj następujące dokumenty, stopniowo przechodząc z prostego do bardziej złożonego:

    • 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. Porządkuj i ujednolicaj dokumentację instalacji botów. Wszystkie podprojekty powinny mieć ujednolicony zestaw instrukcji dotyczących kopiowania repozytorium botów i instalowania wymaganych zależności, szybkiego rozpoczynania pracy, pracy z botem po pierwszym uruchomieniu i wdrażania.

  3. Prezentacja dokumentacji pakietu SDK JS Rocket.Chat. Dokumentację pakietu SDK należy wygenerować programowo z kodu źródłowego przy użyciu specjalistycznych narzędzi. To ulepszenie zwiększy czytelność i wyeliminuje konieczność ręcznego aktualizowania dokumentu w GitHubie za każdym razem, gdy zmieni się metoda (lub coś w niej).

Przebieg

Okres sprawdzania zgłoszeń: zapoznaj się ze społecznością i osobami, z którymi chcesz współpracować. Poznaj przewodniki i sprawdzone metody dotyczące wkładu społeczności. Opublikuj pierwsze wpisy.

Więź społeczności: poznaj społeczność. Sprawdź obecny stan dokumentacji bota. Wskaż słabe punkty.

Tydzień 1: uzgodnij z mentorami nową wizję botów. Utwórz zaktualizowaną zawartość nowej strony głównej botów zgodnie z wizją.

Tydzień 2: przegląd botów, architektura, konfiguracja środowiska

Tydzień 3 – Zdefiniuj listę podprojektów (repozytorium bota github), które należy przenieść do głównej dokumentacji. – Określ, jak mają działać strony internetowe botów po przeniesieniu. – Utwórz szablon, którego użyjesz do uporządkowania informacji w tych repozytoriach. – Przygotowanie głównej dokumentacji do przeniesienia

Tydzień 4: przeniesienie repozytorium bBot. Uporządkuj informacje zgodnie z zdefiniowanym szablonem

Tydzień 5. Przenieś repozytorium Hubot. Uporządkuj informacje zgodnie z zdefiniowanym szablonem

Tydzień 6. Przenieś repozytorium Botkit. Uporządkuj informacje zgodnie z zdefiniowanym szablonem

Tydzień 7. Przenieś repozytorium Rasa. Uporządkuj informacje zgodnie z zdefiniowanym szablonem

Tydzień 8. Przenieś repozytorium BotPress. Uporządkuj informacje zgodnie z zdefiniowanym szablonem

Tydzień 9: finalizacja struktury dokumentacji i stron po przeniesieniu wszystkich podprojektów botów

Tydzień 10. Sprawdź konfigurację JSDoc. Określ miejsce przechowywania artefaktów JSDoc. Rozpocznij dokumentowanie metod kierowców

Tydzień 11: zakończenie dokumentowania metod kierowców

Tydzień 12: Ocena wyników

SZCZEGÓŁOWY ROZDZIAŁ SKŁADÓW MILOWYCH

OKRES SPRAWDZANIA APLIKACJI

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

W drugiej części szkolenia omówimy ogólnie kulturę twórczą i sprawdzone metody publikowania treści. To będzie czas na pierwsze posty, aby przekonać się, jak działa proces.

SPOŁECZNOŚĆ SPOŁECZNOŚCI

Poświęcimy ten czas na dogłębne przeanalizowanie repozytorium dokumentacji oraz jego planu działania. Na podstawie tych informacji można zidentyfikować słabe punkty (np. niekompletne lub brakujące elementy), które można poprawić. W miarę możliwości utwórz żądania pull, aby uzupełnić luki.

TYDZIEŃ 1 – TYDZIEŃ 2

Pierwszy tydzień będzie poświęcony komunikacji z mentorami, co pozwoli im dopasować się do nowej dokumentacji dotyczącej botów. Te informacje zostaną dołączone do zmienionych dokumentów, które mają przybliżyć czytelnikom ogólny charakter bota i jego zasady działania.

W drugim tygodniu skupimy się na tworzeniu zawartości nowej strony głównej botów zgodnie z wizją i poprawieniem stron Przegląd botów, Architektura, Konfiguracja środowiska.

Zaktualizowane dokumenty będą bardziej przejrzyste: – nowych programistów chcących utworzyć własne boty; – profesjonalni [boty], którzy chcą projektować, kodować lub testować boty przy użyciu bezpłatnej i łatwej w użyciu platformy lub dostosować się do istniejących botów na tej platformie. – Profesjonalnych programistów botów z określonymi preferencjami dotyczącymi platformy, którzy chcą tworzyć boty dla Rocket.

Zakres prac będzie następujący:

  1. Usuń zbędne sekcje. Na przykład te sekcje zawierają informacje, które się nakładają:
    • W jaki sposób boty wysyłają i odbierają wiadomości? W przeglądzie botów (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Architektura strumieni wiadomości w botach (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Porozmawiaj z botem na stronie Tworzenie użytkowników botów (https://rocket.chat/docs/bots/Creation-bot-users/#talk-to-your-bot)

  2. Popraw sekcje i wyrażenia na stronie Przegląd botów, aby w jasny sposób opisywały ekosystem i funkcje botów zgodnie z zasadą DRY.

    Przejrzyj sekcje i wyrażenia dotyczące informacji „dla zaawansowanych”:

    • Czym jest bot z punktu widzenia kwestii technicznych
    • z czego składa się komponent,
    • Współdziałanie tych komponentów

  3. Napisz krótki przewodnik zawierający opis czynności, które należy wykonać, aby utworzyć bota (z linkiem do dodatkowych informacji w sekcji „Konfigurowanie środowisk botów”). Ten przewodnik zostanie umieszczony na stronie Konfiguracja środowiska.

W ten sposób deweloper będzie mieć jasną wizję robotów i ich możliwości. Od tego momentu deweloper będzie mógł utworzyć swojego pierwszego bota.

Materiały: poprawione, proste w obsłudze przewodniki wprowadzające zawierające informacje o ekosystemie i architekturze botów.

TYDZIEŃ 3–9

Tygodnie 3–9 będzie poświęcone ujednolicaniu wszystkich dokumentów botów w repozytoriach github i przenoszeniu tych dokumentów do głównej dokumentacji (https://rocket.chat/docs/bots/). Działania te można podzielić na kilka iteracji:

  1. Definicja

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

  2. Szablon

    Zdefiniowanie i utworzenie szablonu (sposobu) do porządkowania informacji w podprojektach botów zdefiniowanych w kroku 1. 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 zawierające proste dane (takie jak „uruchomienie bota”) powinny być uzupełnione o prezentację na żywo za pomocą narzędzia Arkusze terminów (https://neatsoftware.github.io/term-sheets/).

    Ponadto, aby ułatwić zrozumienie początkowego etapu „szybki start” (kroki a–d), wszystkie kroki zostaną również połączone w jedną prezentację na żywo.

    Aby nowi użytkownicy mogli czuć się bezpiecznie przed potencjalnymi porażkami, należy udostępnić przykłady kodu w środowisku zabaw (przy użyciu Glitch jako część ekosystemu Rocket Chat), w którym nowicjusze mogą rozmawiać z botami znającymi „przykładowy kod”.

  3. Przygotowanie

    Przygotowanie głównej dokumentacji do przeniesienia. Obejmuje to utworzenie odpowiedniej struktury folderów i stron, a także dostosowanie spisu treści do tej struktury.

    Ostateczna struktura może wyglądać tak:

    • Boty
      • Architektura botów
      • Tworzenie użytkowników botów
      • Konfigurowanie środowiska bota
      • Uruchomienie botów
        • Bot BBot
        • Robot Hubot
        • Botkit
        • Robot Rasa
        • Robot Botpress

  4. Migracja

    Przeprowadź indywidualną migrację zdefiniowanych podprojektów botów do głównej dokumentacji. Każda dokumentacja dotycząca bota ma osobną stronę z podsekcjami, takimi jak bieżąca wersja (np. na temat uruchomienia robota bBot).

    • Uruchomienie botów
      • Bot BBot
      • Robot Hubot
      • Botkit
      • Robot Rasa
      • Robot Botpress

  5. Organizacja

    W programie dostępnych jest kilka aktywności:

    1. Uporządkowanie informacji z każdego repozytorium github botów zgodnie z szablonem zdefiniowanym w 2 kroku.
    2. Przeniesienie 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 łączenie podprojektów botów z tymi komponentami.
    3. Utworzenie przykładowego bota „hello world” dla każdej obsługiwanej platformy. Ten przykład posłuży jako bot ułatwiający rozpoczęcie korzystania z usługi 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 ma rozproszone dokumenty w formie plików README dla programistów. Te pliki README w ogóle nie mają 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) oraz tabelę zawierającą zmienne środowiskowe.

Te aspekty sprawiają, że deweloper (jako nowicjusz) nie ma pojęcia o ogromnym poziomie szczegółów. W rezultacie deweloper nie może uruchomić bota za pomocą kilku poleceń terminala.

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

Przyniesie to takie korzyści: – Ujednolicona struktura ułatwiająca deweloperom rozpoczęcie korzystania z nowych botów; – Jedno źródło wiarygodnych danych dla dokumentacji botów; – Łatwiejsze znajdowanie potrzebnych informacji o każdym bocie dzięki ujednoliconej strukturze.

Materiały dostarczane: uporządkowane w jednym miejscu (główna dokumentacja) łatwych do wykonania instrukcji tworzenia, konfigurowania i uruchamiania botów obsługiwanych przez Rocket.Chat.

TYDZIEŃ 10

W tym tygodniu będziemy poświęcać konfigurowanie pliku JSDoc (https://devdocs.io/jsdoc/) pod kątem maksymalizacji wartości komentarzy w treści. Obejmuje to m.in.:

  1. Sprawdź, czy plik JSDoc jest prawidłowo skonfigurowany do analizowania komentarzy pod kątem metod sterownika (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods).
  2. Zainstaluj motyw postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme), aby wynikowy kod HTML był bardziej jasny i przyjazny dla programistów.
  3. Definiowanie miejsca, w którym będą publikowane artefakty dokumentacji JSDoc
  4. opis wszystkich funkcji (w pliku dist/lib/driver.js) związanych z metodami sterownika. Obejmuje to m.in.:
    • Dodawanie i edytowanie opisów metod
    • Dodawanie i edytowanie opisów parametrów metody
    • Dodawanie i edytowanie przykładowych żądań metody (w stosownych przypadkach)
    • Dodawanie i edytowanie przykładowych odpowiedzi metody (w razie potrzeby)

Dokumentacja wbudowana jest łatwiejsza w obsłudze z perspektywy dewelopera, a mechanizm automatycznego generowania pozwala pozbyć się dokumentacji statycznej hostowanej na GitHubie (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods), która musi być aktualizowana oddzielnie dla każdej zmiany metod pakietu SDK.

TYDZIEŃ 11

W tym tygodniu zostanie w pełni poświęcony sfinalizowaniu opisu metod kierowców. Po zakończeniu sprawdzimy prawidłowość i spójność opisów, a następnie opublikujemy nową dokumentację.

TYDZIEŃ 12

Finalizowanie ukończonych prac. Kontrole akceptacji.