Rocket.Chat projesi

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

Proje özeti

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

Proje açıklaması

PROJE ÖZETİ

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

Kapsamlı ve net belgelere sahip olmak daha da önemli hale gelir. Bu nedenle, mevcut bot belgelerine erişim ve gezinme daha kolay hale getirilmeli, 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 kurtulmak için düzenlemenin düzeltilmesi gerekir.

Projenin hedefi, bilgi boşluğunu kapatmak ve daha az deneyimli yeni geliştiricileri son teknolojinin faydalarını heyecanlı bir kitleye sunmaya teşvik etmektir. Bunun için, bot geliştiricilerin Rocket.Chat'te kendi botlarını geliştirmeleri için kolay bir deneyim sunabilirsiniz. Bu hedefin amacı, nihai BOT dağıtım hedefinden bağımsız olarak Rocket.Chat'i bu geliştiricilerin chatbot fikirlerini yenilemesi, oluşturması ve test etmesi için tercih edilen açık kaynak platform haline getirmektir.

Proje Sorunları

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

  1. Bot'lar hakkında sezgisel olmayan ve iyi olmayan genel bilgiler
  2. Bot mimarisiyle ilgili, dağınık ve gereksiz bölümler
  3. Tek ve doğru kaynağı olmayan, dağınık "başlangıç" kılavuzu talimatları
  4. Talimat eksikliği veya aşırı miktarda talimat ayrıntısı
  5. Örtülü ve muğlak Bot SDK belgeleri

PROJE TEKLİFİ

Projenin hedefine ve yukarıda ana hatlarıyla açıklanan sorunlara göre, önerilen geliştirmelerin listesi aşağıda verilmiştir:

  1. Bot belgelerini güncelleme. İlk girişin sorunsuz ve tutarlı olması için aşağıdaki dokümanların basitten daha karmaşıka kademeli geçişle güncellenmesi gerekir:

    • 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ıca kullanmaya başlama, ilk lansmandan sonra bot ile çalışma ve bot'un nasıl dağıtılacağı konusunda birleşik bir talimat grubu olmalıdır.

  3. Rocket.Chat JS SDK dokümanlarının sunumunu gözden geçirin. SDK belgeleri, özel araçlar kullanılarak kaynak koddan programatik olarak oluşturulmalıdır. Bu iyileştirme, okunabilirlik kazandıracak 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ıracak.

Önemli Dakikalar

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

Topluluk Bağışı: Topluluğu keşfedin. Bot belgelerinin mevcut durumunu inceleyin. Zayıf noktaları belirleyin.

1. Hafta: Bot'ların yeni vizyonu konusunda mentorlarla fikir birliğine varın. Yeni Bot'lar Ana Sayfası için vizyona uygun güncellenmiş içerik hazırlayın.

2. Hafta: Revizyon Bot'larına Genel Bakış, Mimari, Ortam sayfalarının yapılandırılması

3. Hafta - Ana belgelere aktarılması gereken alt projelerin (bot github havuzları) 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ü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üzenleme

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

9. Hafta: Tüm bot alt projeleri aktarıldıktan sonra ana belge yapısı ve sayfalarının kesinleşmesi

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

AŞAMALARIN AYRINTILI DÖKÜMÜ

BAŞVURU İNCELEME DÖNEMİ

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

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

TOPLULUK BAĞLAMA

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

1. HAFTA - 2. HAFTA

İlk hafta, Bot'lar için yeni vizyon hakkında fikir edinme amacıyla 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ş belgeler arasında yer alacak.

İkinci hafta, Bot'lara Genel Bakış, Mimari ve Ortam Yapılandırma sayfalarının vizyonunu ve revize edilen Bot'lar Ana Sayfası için içerik oluşturmayı ele alacak.

Düzeltilen belgelerde şu noktalara daha net odaklanacağız: - Kendi bot'unu oluşturmak isteyen yeni geliştiriciler - Botlarını ücretsiz ve kullanımı kolay bir platform kullanarak tasarlamak/kodlamak/test etmek veya mevcut botlarını bu platforma uyarlamak isteyen profesyonel [bot] geliştiricileri - Çerçeve tercihleri Roket için bot oluşturmak isteyen profesyonel bot geliştiricileri.Chat

Çalışmanın kapsamı şöyle olacaktır:

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

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

    "Gelişmiş" bilgileriyle 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 ("Bot ortamlarını yapılandırma" ile ilgili daha fazla bilgi edinin). Bu kılavuz, Ortam Yapılandırması sayfasının altına yerleştirilecektir.

Bu sayede, bir geliştirici botların yapısına ve neler yapabildiğine dair net bir vizyona sahip olur. Bir geliştirici, o noktadan sonra ilk botunu oluşturabilir.

Teslimatlar: Bot ekosistemi ve mimarisiyle ilgili bilgilerin yer aldığı, gözden geçirilmiş, takibi kolay tanıtım kılavuzları.

3. HAFTA - 9

3. ila 9. haftalar, tüm bot dokümanlarının gitHub depolarında birleştirilmesine ve bu dokümanların ana belgelere (https://rocket.chat/docs/bots/) aktarılmasına ayrılmıştı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ı botlar, 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 (yol) 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ırın

    e. Gelişmiş yapılandırma

    f. Diğer adımlar

    Basit olmayan bazı çıktıları içeren komutlara (""bot çalıştır" gibi) Terim E-Tablolar aracıyla (https://neatsoftware.github.io/term-sheets/) o çıkışın 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 tek bir canlı sunuda birleştirilir.

    Yeni kullanıcıların olası hatalara 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 (Rocket Chat ekosisteminin bir parçası olarak Glitch kullanılarak) kod örnekleri sağlanmalıdır.

  3. Hazırlık

    Aktarım için temel 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'u
        • Botpress Bot'u

  4. Taşıma

    Tanımlanan bot alt projelerini tek tek ana belgelere taşıma. Bot dokümanlarının her parçası, geçerli sürüm (ör. bBot çalıştırma) gibi alt bölümlerin bulunduğu ayrı bir sayfaya sahiptir.

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

  5. Kuruluş

    Çeşitli etkinlikler olacak:

    1. Her 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 "hello world" 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 tümü: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy'nin README'leri biçiminde, dağınık dokümanlar. Bu README'ler hiçbir yapıya sahip değildir, nasıl başlanacağı konusunda eski bilgiler veya bazen de hubot (https://github.com/RocketChat/hubot-rocketchat) gibi Docker kullanarak bot çalıştırma hakkında üçlü yedeklilik içeren) ve çevresel değişkenleri içeren bir tablo içerir.

Bu özellikler, yeni başlayan bir geliştiriciyi olağanüstü ayrıntı düzeyiyle karıştırır. Sonuç olarak geliştirici, yalnızca birkaç terminal komutu kullanarak bot'u çalışır duruma getiremez.

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

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 belgeleri için tek ve bilgi kaynağı - Birleştirilmiş yapı sayesinde botlarla ilgili gerekli bilgilerin bulunması daha kolaydır

Teslim edilecek materyaller: Tek bir yerde düzenlenir (ana dokümanlar), Rocket.Chat tarafından desteklenen botların nasıl oluşturulacağına, yapılandırılacağına ve çalıştırılacağına ilişkin, uygulaması kolay talimatlar.

10. HAFTA

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

  1. JSDoc'un, sürücü yöntemleri için yorumları ayrıştıracak şekilde doğru yapılandırıldığından emin olma (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Elde edilen HTML çıkışını daha açık ve geliştirici dostu hale getirmek için postman-jsdoc-theme'yi (https://github.com/postmanlabs/postman-jsdoc-theme) yükleyin.
  3. JSDoc dokümantasyonu 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
    • Varsa yöntem isteği örnekleri ekleme/düzenleme
    • Varsa 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. Otomatik oluşturma mekanizması ise GitHub'da (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) barındırılan ve SDK yöntemlerindeki her değişiklikten ayrı olarak güncellenmesi gereken statik dokümanlardan kurtulmanızı sağlar.

11. HAFTA

Bu hafta yalnızca sürücü yöntemlerini açıklama bölümünün son hâline gelecek. Açıklamalar tamamlandıktan sonra doğruluk ve tutarlılık açısından test edilir. Ardından yeni belgeler tüm dünyada yayınlanır.

12. HAFTA

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