Rocket.Chat projesi

Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.

Proje özeti

Açık kaynak kuruluşu:
Rocket.Chat
Teknik yazar:
Kısmetli Altın
Projenin adı:
Bot Dokümanları
Proje süresi:
Standart uzunluk (3 ay)

Proje açıklaması

PROJE ÖZETİ

Chat Bot'lar günümüzün teknolojisinin en ileri teknolojileridir. Sohbet yazılımları ve bot'larındaki genel büyüme oranları ile konuşma tanıma ve otomasyon arasındaki artış, anlaşılması ve kullanılması kolay bot belgeleri oluşturma ihtiyacını ortaya koyuyor.

Kapsamlı ve net belgelere sahip olmak daha da önemli hale geldiğinden, mevcut bot belgelerine erişim ve gezinmenin kolaylaştırılması, desteklenen her çerçeve için birleştirilmiş adım adım talimatlar ve kapsamlı örnekler sağlanmalıdır. Ayrıca gereksiz ve anlaşılması zor bilgilerden kurtulacak şekilde düzenlenmelidir.

Projenin hedefi, bilgi boşluğunu kapatmak ve yeni, daha az deneyimli geliştiricileri son teknolojinin faydalarını heyecanlı bir kitleye sunmaya teşvik etmektir. Bunu başarmak için, bot geliştiricilerin Rocket.Chat'te kendi botlarını geliştirmeleri için kolay bir deneyim sunabilirsiniz. Bu hedef; Rocket.Chat'i, nihai BOT dağıtım hedefinden bağımsız olarak Chatbot fikirlerini inovasyon, geliştirme ve test etme konusunda bu geliştiricilerin tercih ettiği açık kaynak platform haline getirmeyi amaçlar.

Proje Sorunları

Bot belgeleriyle ilgili en önemli sorunların listesi aşağıda verilmiştir:

  1. Bot'lar hakkında pratik ve iyi olmayan genel bilgiler
  2. Bot mimarisiyle ilgili dağınık ve gereksiz bölümler
  3. "Başlangıç" bölümündeki dağınık haldeki kılavuz talimatları, tek ve doğru bir kaynak değildir
  4. Talimat eksikliği veya çok fazla talimat ayrıntısı
  5. Dolaylı ve belirsiz Bot SDK dokümanları

PROJE TEKLİFİ

Projenin hedefine ve yukarıda özetlenen sorunlara göre, önerilen geliştirmelerin listesi aşağıda verilmiştir:

  1. Bot belgelerini güncelleyin. İlk tanıtımın sorunsuz ve tutarlı olması için aşağıdaki dokümanlar, basitten daha karmaşığa kademeli 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/
    • Bot'lar 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 deposunu klonlama ve gerekli bağımlılıkları yükleme, hızlı başlangıç yapma, ilk lansmandan sonra bot ile çalışma ve bot'un nasıl dağıtılacağı konusunda birleşik talimatlar bulunmalıdır.

  3. Rocket.Chat JS SDK'sı dokümanlarının sunumunu revize edin. SDK belgeleri, özel araçlar kullanılarak kaynak koddan programatik olarak oluşturulmalıdır. Bu iyileştirme, okunabilirlik sağlayacak ve bir yöntem (ya da içindeki bir şey) her değiştiğinde GitHub'daki dokümanın manuel olarak güncellenmesi ihtiyacını ortadan kaldıracaktır.

Önemli Dakikalar

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

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

1. hafta: Danışmanlarla Bot'ların yeni vizyonu konusunda fikir birliğine varın. Yeni Bot'lar Ana Sayfası için vizyona uygun şekilde güncellenmiş içerik oluşturmak.

2. Hafta: Bot'ları Gözden Geçirmeye Genel Bakış, Mimari, Ortam sayfalarının yapılandırılması

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

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

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

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

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üzenleyin

9. Hafta: Tüm bot alt projelerini aktardıktan sonra ana belge yapısının ve sayfaların kesinleştirilmesi

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şlayın

11. hafta: Sürücü yöntemlerini belgeleme işlemini tamamlayın

12. Hafta: Sonuçları değerlendirme

ARA HEDEFLERİN AYRINTILI DÖKÜMÜ

BAŞVURU İNCELEME DÖNEMİ

Dönemin ilk bölümü topluluk kanallarını ve kaynak kodunu kontrol etmeye ve projeye bağlı kişilerle iletişime geçmeye ayrılacaktır.

Dönemin ikinci bölümünde ise katkı kılavuzları ve en iyi uygulamalar incelenecek ve genel olarak katkı kültürünü incelemeye ayrılacağız. Bu, akışın nasıl çalıştığını görmek için ilk kez katkıda bulunma zamanıdır.

TOPLULUK BAĞLAMASI

Bu süre, belge deposunun ve yol haritasının daha ayrıntılı bir şekilde incelenmesine ayrılacaktır. Bu bilgiler ışığında, iyileştirilebilecek zayıf noktaları (ör. eksik veya eksik parçalar) belirlemek mümkün olabilir. Boşlukları doldurmak için çekme istekleri (mümkünse) oluşturun.

1. HAFTA - 2. HAFTA

Bot'lar için yeni vizyon dokümanları konusunda karar vermek için ilk hafta mentorlarla iletişime geçmeye ayıracak. Bu bilgiler, okuyuculara bot'un ne olduğu ve çalışma ilkeleri hakkında genel bir bakış sunmak amacıyla gözden geçirilmiş dokümanların bir parçası olacak.

İkinci hafta, Bot'lara Genel Bakış, Mimari ve Ortam Yapılandırılması sayfaları için vizyon ve revize etme doğrultusunda yeni Bot'lar Ana Sayfası için içerik oluşturma hakkında olacak.

Düzeltilen belgelerde aşağıdaki konulara daha net odaklanılacak: - Kendi bot'unu oluşturmak isteyen yeni geliştiriciler - Ücretsiz ve kullanımı kolay bir platform kullanarak bot'larını tasarlamak/kodlamak/test etmek veya mevcut bot'larını bu platforma uyarlamak isteyen profesyonel [bot] geliştiricileri - Çerçeve tercihleri olan ve Rocket için bot oluşturmak isteyen profesyonel bot geliştiricileri

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

  1. Gereksiz bölümleri kaldırın. Örneğin, aşağıdaki bölümlerde çakışan bilgiler paylaşılır:
    • Botlar nasıl ileti gönderip alır? Bot'lara Genel Bakış'ta (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Bot Mimarisi'nde Mesaj Akışları (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Bot Kullanıcıları Oluşturma (https://rocket.chat/docs/bots/render-bot-users/#talk-to-your-bot) bölümünde bot'unuzla konuşun

  2. Bot ekosistemini ve işlevselliğini DRY ilkesine uygun şekilde net bir şekilde açıklayacak şekilde Bot'lara Genel Bakış sayfasının bölümlerini ve ifadelerini gözden geçirin.

    "Gelişmiş" bilgilerle ilgili bölümleri ve ifadeleri gözden geçirmek:

    • Bot, teknik açıdan ne anlama gelir?
    • Hangi bileşenlerden oluşur?
    • Bu bileşenler birlikte nasıl çalışır?

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

Bu sayede geliştirici, bot'ların doğası ve yapabilecekleri hakkında net bir fikir sahibi olur. Bu noktadan sonra, geliştirici ilk botunu oluşturabilir.

Teslimatlar: Bot ekosistemi ve mimarisi hakkında bilgiler içeren, yeniden düzenlenmiş ve takibi kolay tanıtım kılavuzları.

3. HAFTA - 9

3. ila 9. haftalar, tüm bot belgelerinin gitHub depolarında birleştirilmesine ve bu belgelerin ana belgeye (https://rocket.chat/docs/bots/) aktarılmasına ayrılacaktır. Bu etkinlikler birkaç yinelemeye 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 (bazı bot'lar, bbot'lar, örneğin (http://bbot.chat)) github'ın yanı sıra dokümanlar da içeren ayrı sitelere sahip olmalıdır.

  2. Şablon

    1. adımda tanımlanan bot alt projelerindeki bilgileri düzenlemek için bir şablon (bir 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'u yapılandırma

    d. Bot çalıştırma

    e. Gelişmiş yapılandırma

    f. Diğer adımlar

    Basit olmayan bazı çıkışlar içeren komutlara ("bot çalıştır" gibi) Terim E-Tablolar aracıyla (https://neatsoftware.github.io/term-sheets/) ait canlı sunumlar eşlik etmelidir.

    Ayrıca başlangıçtaki ""hızlı başlangıç"" aşamasını (a - d arasındaki adımlar) daha net hale getirmek için tüm adımlar aynı zamanda tek bir canlı sunuda birleştirilir.

    Yeni gelenlerin olası arızalara karşı güvende hissetmelerini sağlamak için, yeni kullanıcıların arka planda "örnek kod" bulunan botlarla sohbet edebileceği oyun alanında (Glitch kullanılarak) kod örnekleri sağlanmalıdır.

  3. Hazırlık

    Aktarım için ana belgeleri hazırlama. Bu, uygun klasör ve sayfa yapısının oluşturulmasının yanı sıra içindekiler tablosunu bu yapıya göre ayarlamayı da kapsar.

    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
      • Botları Çalıştır
        • bBot Bot
        • Hubot Bot'u
        • Botkit Bot'u
        • Rasa Bot
        • Botpress Botu

  4. Taşıma

    Tanımlanan bot alt projelerini ana belgelere tek tek taşıma. Bot dokümanlarının her parçasının, mevcut sürüm gibi alt bölümleri (ör. bBot çalıştırma) içeren ayrı bir sayfası olur.

    • Botları Çalıştır
      • bBot Bot
      • Hubot Bot'u
      • Botkit Bot'u
      • Rasa Bot
      • Botpress Botu

  5. Kuruluş

    Birkaç etkinlik olacak:

    1. Her bir bot gitHub deposundaki bilgileri 2. adımda tanımlanan şablona göre düzenleme.
    2. Tüm bot alt projeleriyle ilgili ortak bileşenleri (ör. ortam değişkenleri) ana belgenin 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ıç" bot'u olarak kullanılacaktır.

Bu neden önemli? Rocket.Chat tarafından desteklenen 8 alt projenin tamamı: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy, README'ler şeklinde dağınık belgeler içeriyor. Bu README'ler hiçbir yapıya sahip değildir, nasıl başlayacağınızla ilgili güncel olmayan bilgiler içerir veya çok fazla bilgi (bazen, hubot (https://github.com/RocketChat/hubot-rocketchat) gibi üçlü yedeklilik içerenler) Docker kullanarak bot çalıştırmanın yanı sıra çevresel değişkenleri de içeren bir tablo içerir.

Bu özellikler, (yeni başlayanlar için) geliştiricileri muazzam ayrıntı düzeyiyle karıştırır. Sonuç olarak geliştirici, yalnızca birkaç terminal komutu kullanarak bot'u çalıştıramaz.

Aktarım ve optimizasyon tamamlandıktan sonra, github'daki mevcut bot depoları ana dokümanlara referans veren README dosyalarına sahip olur.

Bu değişiklik aşağıdaki avantajları sağlar: - Geliştiricilerin yeni bot'ları kullanmaya başlamasını kolaylaştıran birleşik bir yapı - Bot dokümanları için tek doğru kaynak - Birleştirilmiş yapı sayesinde bot'larla ilgili gerekli bilgiyi bulmak daha kolay

Teslimatlar: Rocket.Chat tarafından desteklenen botların nasıl oluşturulacağına, yapılandırılacağına ve çalıştırılacağına dair uygulaması kolay talimatlar (ana dokümanlar) altında düzenlenir.

10. HAFTA

Bu hafta satır içi yorumların değerini en üst düzeye çıkaracak şekilde JSDoc'u (https://devdocs.io/jsdoc/) yapılandırmaya odaklanacağız. Bu kural kapsamına aşağıdakiler dahildir:

  1. JSDoc'un, sürücü yöntemlerine göre yorumları ayrıştıracak şekilde yapılandırıldığından emin olma (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Ortaya çıkan HTML çıktısını daha açık ve geliştirici dostu hale getirmek için postman-jsdoc-theme'i (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şlevlerin (dist/lib/driver.js) açıklanması. Buna aşağıdakiler dahildir:
    • Yöntemlerin açıklamalarını ekleme/düzenleme
    • Yöntem parametrelerinin açıklamalarını ekleme/düzenleme
    • Yöntem isteği örnekleri (varsa) ekleme/düzenleme
    • Geçerliyse, yöntem yanıtı örnekleri ekleme/düzenleme

Satır içi belgelerin yazılması ve bakımı, geliştiricinin bakış açısından daha kolaydır ve otomatik oluşturma mekanizması, SDK yöntemlerindeki her değişiklikten ayrı olarak güncellenmesi gereken GitHub'da (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) barındırılan statik dokümanlardan kurtulmanızı sağlar.

11. HAFTA

Bu hafta tamamen sürücü yöntemlerini açıklamaya ayrılacak. Açıklamalar tamamlandıktan sonra doğruluk ve tutarlılık açısından test edilir. Ardından yeni dokümanlar dünya genelinde yayınlanır.

12. HAFTA

Tamamlanan çalışmanın kesinleştirilmesi. Kabul kontrolleri.