Rocket.Chat projesi

Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.

Proje özeti

Açık kaynak kuruluşu:
Rocket.Chat
Teknik yazar:
Bay Altın
Proje adı:
Bot Dokümanlar
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

PROJE ÖZETİ

Chat bot'lar günümüz teknolojisinin en ileri noktasındadır. Chat yazılımları ve bot'larda genel olarak görülen yüksek büyüme oranlarının yanı sıra konuşma tanıma ve otomasyonun artması, anlaşılması ve kullanılması kolay bot dokümanları oluşturma ihtiyacını doğuruyor.

Kapsamlı ve net belgelere sahip olmak daha da önemli hale geliyor. Bu nedenle, mevcut bot belgelerine erişimin ve gezinmenin daha kolay hale getirilmesi, desteklenen her çerçeve için birleştirilmiş adım adım talimatlar ve kapsamlı örnekler sunulmalıdır. Ayrıca, gereksiz ve anlaşılması zor bilgilerden kurtulmak için düzenlenmelidir.

Projenin amacı, bilgi eksikliğini gidermek ve yeni, daha az deneyimli geliştiricileri heyecanlı bir kitleye son teknolojinin avantajlarını sunmaya teşvik etmektir. Bu, bot geliştiricilere Rocket.Chat'te kendi botlarını geliştirme konusunda kolaylaştırılmış bir deneyim sunarak yapılabilir. Bu hedef, nihai BOT dağıtım hedefi ne olursa olsun bu geliştiricilerin chatbot fikirlerini geliştirmeleri, oluşturmaları ve test etmeleri için Rocket.Chat'i tercih edilen açık kaynak platform haline getirmeyi amaçlıyor.

Proje Sorunları

Aşağıda, bot dokümanlarıyla ilgili en önemli sorunların listesi verilmiştir:

  1. Bot'larla ilgili anlaşılır olmayan ve kullanıcı dostu olmayan genel bilgiler
  2. Bot mimarisiyle ilgili dağınık ve gereksiz bölümler
  3. Tek bir doğru kaynaktan yararlanmayan, "başlarken" kılavuz talimatlarının dağınık parçaları
  4. Talimat eksikliği veya talimat ayrıntılarının aşırı düzeyde olması
  5. Dolaylı ve belirsiz Bot SDK dokümanları

PROJE TEKLİFİ

Projenin hedefine ve yukarıda belirtilen sorunlara göre önerilen iyileştirmelerin listesi aşağıda verilmiştir:

  1. Bot dokümanlarını güncelleyin. İlk tanıtımın sorunsuz ve tutarlı olması için aşağıdaki dokümanlar, basitten daha karmaşık olana kademeli bir geçişle güncellenmelidir:

    • Bot'lara Genel Bakış: https://rocket.chat/docs/bots/
    • Bot Mimarisi: https://rocket.chat/docs/bots/bots-architecture/
    • Bot ortamlarını yapılandırma: https://rocket.chat/docs/bots/configure-bot-environment/
    • Botlar Ana Sayfası: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Bot yükleme belgelerini düzenleyin ve birleştirin. Tüm alt projelerde, bir bot deposunun nasıl klonlanacağı ve gerekli bağımlılıkların nasıl yükleneceği, hızlı bir şekilde nasıl başlanacağı, ilk çalıştırmadan sonra bir botla nasıl çalışılacağı ve nasıl dağıtılacağıyla ilgili birleşik bir talimat grubu bulunmalıdır.

  3. Rocket.Chat JS SDK doküman sunumunu düzeltin. SDK dokümanları, özel araçlar kullanılarak kaynak kodundan programatik olarak oluşturulmalıdır. Bu iyileştirme, okunabilirliği beraberinde getirecek ve bir yöntem (veya dokümandaki bir şey) her değiştiğinde GitHub'daki dokümanı manuel olarak güncelleme ihtiyacını ortadan kaldıracak.

Önemli Dakikalar

Başvuru İnceleme Dönemi: Toplulukla ve birlikte çalışacağınız kişilerle tanışın. Topluluk katkısı kılavuzları ve en iyi uygulamaları öğrenin. İlk katkıları yapın.

Topluluk Bağışı: Topluluğu keşfedin. Bot dokümanlarının mevcut durumunu inceleyin. Zayıf noktaları belirleyin.

1. Hafta: Bot'larla ilgili yeni vizyon konusunda mentorlarla görüşün. Yeni Botlar Ana Sayfası için vizyona uygun güncellenmiş bir içerik oluşturun.

2. Hafta: Botlara Genel Bakış, Mimari, Ortam Yapılandırması sayfalarını gözden geçirin

3. Hafta - Ana dokümanlara aktarılması gereken alt projelerin (bot github repos) listesini tanımlayın. - Bot web sitelerinin aktarımdan sonra nasıl çalışması gerektiğini tanımlayın. - Bu depolardaki bilgileri düzenlemek için kullanılacak bir şablon tanımlayın. - Aktarım için ana dokümanları hazırlayın

4. Hafta: bBot deposunu aktarın. Bilgileri tanımlanan şablona göre düzenleme

5. Hafta: Hubot deposunu aktarın. Bilgileri tanımlanan şablona göre düzenleme

6. Hafta: Botkit deposunu aktarın. Bilgileri tanımlanan şablona göre düzenleme

7. Hafta: Rasa deposunu aktarın. Bilgileri tanımlanan şablona göre düzenleyin

8. Hafta: BotPress deposunu aktarın. Bilgileri tanımlanan şablona göre düzenleme

9. Hafta: Tüm bot alt projeleri aktarıldıktan sonra ana doküman yapısının ve sayfaların tamamlanması

10. Hafta: JSDoc yapılandırmasını kontrol edin. JSDoc yapılarının depolanacağı bir yer tanımlayın. Sürücü yöntemlerini belgelemeye başlama

11. Hafta: Sürücü yöntemlerini belgelemeyi tamamlayın

12. Hafta: Sonuçları değerlendirme

AYRINTILI ARA HEDEF DÖKÜMÜ

BAŞVURU İNCELEME DÖNEMİ

Dönemin ilk bölümünde topluluk kanallarını ve kaynak kodunu kontrol etmeye ve projeye özel kişilerle iletişim kurmaya odaklanacağız.

Dönemin ikinci bölümünde ise genel olarak katkı kültürünü kontrol etmek, katkı kılavuzlarını ve en iyi uygulamaları incelemek için çalışacağız. Bu, sürecin nasıl işlediğini görmek için ilk katkıların sunulduğu zamandır.

TOPLULUK BAĞI

Bu bölümde, yol haritasıyla birlikte belge deposunu daha ayrıntılı bir şekilde incelemeye ayıracağız. Bu bilgilere dayanarak, geliştirilebilecek zayıf noktalar (ör. eksik veya eksik parçalar) belirlenebilir. Boşlukları doldurmak için (mümkün olduğunda) çekme isteği oluşturun.

1. HAFTA - 2. HAFTA

İlk hafta, Bot dokümanları için yeni vizyonla uyum sağlamak amacıyla mentorlarla iletişime geçilecek. Bu bilgiler, okuyuculara bot'un ne olduğu ve çalışma ilkeleri hakkında genel bir bakış sunmayı amaçlayan revize edilmiş dokümanların bir parçası olacaktır.

İkinci haftada, yeni Botlar Ana Sayfası için vizyona uygun içerikler oluşturacak ve Botlar'a Genel Bakış, Mimari, Ortam Yapılandırması sayfalarını gözden geçireceğiz.

Düzeltilen belgelerde aşağıdakilere odaklanılacak: - Kendi botlarını oluşturmak isteyen yeni geliştiriciler - Ücretsiz ve kullanımı kolay bir platform kullanarak botlarını tasarlamak/kodlamak/test etmek veya mevcut botlarını bu platforma uyarlamak isteyen profesyonel [bot] geliştiriciler - Rocket.Chat için bot oluşturmak isteyen, çerçeve tercihleri olan profesyonel bot geliştiriciler

Çalışmanın kapsamı aşağıdaki gibi olacak:

  1. Gereksiz bölümleri kaldırın. Örneğin, aşağıdaki bölümlerde çakışan bilgiler paylaşılır:
    • Bot'lar nasıl mesaj gönderir ve alır? Bot'lara Genel Bakış (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Bot Mimarisi'ndeki Mesaj Akışları (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Bot Kullanıcıları Oluşturma (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot) başlıklı makalede botunuzla nasıl konuşacağınızı öğrenebilirsiniz.

  2. Bot'lara Genel Bakış sayfasının bölümlerini ve ifadelerini, DRY ilkesine uygun olarak bot ekosistemini ve işlevini net bir şekilde açıklayacak şekilde düzeltin.

    "Gelişmiş seçenekler" ile ilgili bölümleri ve ifadeleri gözden geçirin:

    • Teknik açıdan bot nedir?
    • Hangi bileşenlerden oluşur?
    • Bu bileşenlerin birlikte çalışma şekli

  3. Bot oluşturmak için gereken adımları açıklayan bir hızlı başlangıç kılavuzu yazın (daha fazla bilgi için "Bot ortamlarını yapılandırma" bağlantısını ekleyin). Bu kılavuz, Ortam Yapılandırması sayfasının altına yerleştirilecek.

Bu sayede geliştiriciler, botların doğası ve neler yapabilecekleriyle ilgili net bir vizyona sahip olur. Geliştiriciler artık ilk bot'unu oluşturabilir.

Teslimatlar: Bot ekosistemi ve mimarisi hakkında bilgi içeren, gözden geçirilmiş ve uygulaması kolay tanıtım rehberleri.

3. - 9. HAFTA

3. ila 9. haftalar, github depolarındaki tüm bot dokümanlarını birleştirmeye ve bu dokümanları ana dokümanlara (https://rocket.chat/docs/bots/) aktarmaya ayrılacak. Bu etkinlikler birkaç iterasyona ayrılabilir:

  1. Tanım

    Ana belgelere taşınması gereken bot alt projelerinin listesini tanımlama. Bot web sitelerinin aktarımdan sonra nasıl çalışması gerektiğini tanımlayın (ör. bbot (http://bbot.chat) gibi bazı botların github'a ek olarak dokümanları olan ayrı siteleri vardır).

  2. Şablon

    1. adımda tanımlanan bot alt projelerindeki bilgileri düzenlemek için bir şablon (yöntem) tanımlama ve oluşturma. Bu şablon aşağıdaki gibi görünebilir:

    a. Depo klonlama

    b. Bağımlıları yükleme

    c. Bot yapılandırması

    d. Bot çalıştırma

    e. Gelişmiş yapılandırma

    f. Sonraki adımlar

    "Bot çalıştır" gibi önemli sonuçlar içeren komutlara, Term Sheets aracı (https://neatsoftware.github.io/term-sheets/) kullanılarak bu sonuçların canlı sunumu eklenmelidir.

    Ayrıca, ilk "hızlı başlangıç" aşamasını (a-d adımları) daha net hale getirmek için tüm adımlar tek bir canlı sunumda birleştirilecek.

    Yeni başlayanların olası arızalara karşı güvende hissetmelerini sağlamak için oyun ortamıyla birlikte kod örnekleri sağlanmalıdır (Roket Sohbet ekosisteminin bir parçası olarak Glitch kullanılarak), yeni katılımcıların kabinde "örnek kod" bulunan botlarla sohbet edebileceği oyun alanı ortamı (Glitch kullanılarak).

  3. Hazırlık

    Aktarım için ana dokümanları hazırlama. Doğru klasör ve sayfa yapısının oluşturulması ve içindekiler tablosunun bu yapıya göre ayarlanması da buna dahildir.

    Nihai yapı aşağıdaki gibi görünebilir:

    • Bot'lar
      • Bot mimarisi
      • Bot kullanıcıları oluşturma
      • Bot Ortamını Yapılandırma
      • Bot çalıştırma
        • bBot Bot
        • Hubot Bot
        • Botkit Bot
        • Rasa Bot
        • Botpress Bot

  4. Taşıma

    Tanımlanmış bot alt projelerini ana dokümanlara tek tek taşıma Her bot dokümanı, geçerli sürüm gibi alt bölümler içeren ayrı bir sayfaya (ör. bBot çalıştırma) sahip olacaktır.

    • Bot çalıştırma
      • bBot Bot
      • Hubot Bot
      • Botkit Bot
      • Rasa Bot
      • Botpress Bot

  5. Kuruluş

    Birkaç etkinlik olacak:

    1. Her botun GitHub deposundaki bilgileri 2. adımda tanımlanan şablona göre düzenleme.
    2. Tüm bot alt projeleriyle ilgili ortak bileşenleri (ör. çevresel değişkenler) ana belgelerin hiyerarşisinde bir seviye yukarı taşıma ve bot alt projelerini bu bileşenlere bağlama
    3. Desteklenen her çerçeve için bir "merhaba dünya" botu örneği oluşturma. Bu örnek, Rocket.Chat için "başlangıç" botu olarak kullanılacaktır.

Bu neden önemli? Rocket.Chat tarafından desteklenen 8 alt projenin tümü (alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy) geliştirici README'leri şeklinde dağınık dokümanlara sahiptir. Bu README'ler hiç yapıya sahip değil, başlangıçla ilgili güncel olmayan bilgiler içeriyor veya çok fazla bilgi (bazen Docker'ı kullanarak bot çalıştırma hakkındaki hubot (https://github.com/RocketChat/hubot-rocketchat) gibi üçlü yedeklemeyle) ve ortam değişkenlerini içeren tablo içeriyor.

Bu özellikler, yeni başlayan bir geliştiricinin kafasını karıştıracak kadar ayrıntılı. Sonuç olarak geliştirici, yalnızca birkaç terminal komutuyla bir botu kurup çalıştıramaz.

Aktarım ve optimizasyon tamamlandıktan sonra, github'daki mevcut bot depolarında ana dokümanlara atıfta bulunan README dosyaları bulunur.

Bu sayede aşağıdaki avantajlardan yararlanabilirsiniz: - Geliştiricilerin yeni botlarla çalışmaya başlamasını kolaylaştıran birleşik bir yapı - Bot dokümanları için tek bir doğru kaynak - Birleşik yapı sayesinde herhangi bir botla ilgili gerekli bilgileri daha kolay bulma

Teslimatlar: Rocket.Chat tarafından desteklenen bot'ları oluşturma, yapılandırma ve çalıştırmayla ilgili takibi kolay talimatlar, tek bir yerde (ana belgeler) düzenlenir.

10. HAFTA

Bu hafta, satır içi yorumların değerini en üst düzeye çıkarmak için JSDoc'u (https://devdocs.io/jsdoc/) yapılandırmaya odaklanacağız. Bunlardan bazıları:

  1. JSDoc'un, sürücü yöntemleriyle ilgili yorumları ayrıştıracak şekilde doğru şekilde yapılandırıldığından emin olun (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods).
  2. Elde edilen HTML çıktısını daha açık ve geliştirici dostu hale getirmek için postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) yükleyin.
  3. JSDoc doküman yapılarının yayınlanacağı yeri tanımlama
  4. Sürücü yöntemleriyle ilgili tüm işlevleri (dist/lib/driver.js içinde) açıklamak. Buna aşağıdakiler dahildir:
    • Yöntem açıklamaları ekleme/düzenleme
    • Yöntem parametrelerinin açıklamalarını ekleme/düzenleme
    • Varsa yöntem isteklerine örnek ekleme/düzenleme
    • Varsa yöntem yanıtı örnekleri ekleme/düzenleme

Geliştirici, satır içi dokümanları yazmak ve yönetmek daha kolaydır. Otomatik oluşturma mekanizması, GitHub'da barındırılan ve SDK yöntemlerindeki her değişiklikte ayrı ayrı güncellenmesi gereken statik belgelerden (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) kurtulmanıza olanak tanır.

11. HAFTA

Bu hafta, tamamen sürücü yöntemlerini açıklamaya ayrılacak. Tamamlandıktan sonra açıklamalar doğruluk ve tutarlılık açısından test edilecek ve ardından yeni belgeler dünyada yayınlanacak.

12. HAFTA

Tamamlanan çalışmanın tamamlanması. Kabul kontrolleri.