Project Rocket.Chat

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.

Ringkasan proyek

Organisasi open source:
Rocket.Chat
Penulis teknis:
Tister Emas
Nama proyek:
Dokumen Bot
Durasi proyek:
Durasi standar (3 bulan)

Project description

RINGKASAN PROYEK

Bot Chat adalah teknologi mutakhir saat ini. Tingkat pertumbuhan keseluruhan yang besar pada software chat dan bot, beserta pengenalan ucapan dan otomatisasi yang sedang meningkat, menentukan kebutuhan untuk membuat dokumentasi bot yang mudah dipahami dan digunakan.

Dokumentasi yang komprehensif dan jelas menjadi semakin penting, sehingga dokumentasi bot yang ada harus dibuat lebih mudah diakses dan dinavigasi, harus menyediakan petunjuk langkah demi langkah yang terpadu untuk setiap framework yang didukung, serta contoh yang ekstensif. Data itu juga harus dirapikan untuk menyingkirkan informasi yang berlebihan dan sulit dipahami.

Tujuan proyek ini adalah untuk menjembatani kesenjangan pengetahuan dan mendorong developer baru yang kurang berpengalaman untuk menghadirkan manfaat teknologi mutakhir kepada audiens yang antusias. Hal ini dapat dilakukan dengan memberi pembuat bot pengalaman yang sederhana dalam mengembangkan bot mereka sendiri di Rocket.Chat. Sasaran ini bertujuan menjadikan Rocket.Chat sebagai platform open source pilihan bagi para developer untuk berinovasi, membuat, dan menguji ide chatbot mereka - terlepas dari target deployment BOT akhir.

Masalah Project

Berikut adalah daftar masalah paling penting terkait dokumentasi bot:

  1. Informasi umum yang tidak intuitif dan tidak ramah tentang bot
  2. Bagian yang tersebar dan redundan terkait dengan arsitektur bot
  3. Potongan petunjuk "memulai" yang tidak teratur tanpa sumber informasi apa pun
  4. Kurangnya instruksi atau terlalu banyak detail petunjuk
  5. Dokumentasi SDK Bot yang implisit dan tidak jelas

PROPOSAL PROYEK

Menurut tujuan proyek, dan masalah yang diuraikan di atas, berikut ini adalah daftar perbaikan yang diusulkan:

  1. Mengupdate dokumen bot. Agar pengantar awal berjalan lancar dan konsisten, dokumen berikut harus diperbarui secara bertahap dari yang sederhana ke lebih kompleks:

    • Ringkasan Bot: https://rocket.chat/docs/bots/
    • Arsitektur Bot: https://rocket.chat/docs/bots/bots- Architecture/
    • Mengonfigurasi lingkungan bot: https://rocket.chat/docs/bots/configure-bot-environment/
    • Halaman Beranda Bot: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Mengatur dan menyatukan dokumentasi penginstalan bot. Semua sub-project harus memiliki serangkaian petunjuk terpadu tentang cara meng-clone repositori bot dan menginstal dependensi yang diperlukan, cara memulai dengan cepat, cara menggunakan bot setelah peluncuran pertama, dan cara men-deploy-nya.

  3. Merevisi presentasi dokumentasi Rocket.Chat JS SDK. Dokumentasi SDK harus dibuat secara terprogram dari kode sumber menggunakan alat khusus. Peningkatan ini akan meningkatkan keterbacaan dan meniadakan kebutuhan untuk memperbarui dokumen di GitHub secara manual setiap kali metode (atau sesuatu di dalamnya) berubah.

Linimasa

Periode Peninjauan Pendaftaran: Kenali komunitas dan orang-orang yang bekerja sama dengan Anda. Pelajari panduan dan praktik terbaik kontribusi komunitas. Berikan kontribusi pertama.

Ikatan Komunitas: Jelajahi komunitas. Memeriksa status dokumentasi bot saat ini. Identifikasi titik lemah.

Minggu ke-1: Berselaraskan dengan mentor tentang visi baru Bot. Membuat konten terupdate untuk Halaman Beranda Bot baru sesuai dengan visi.

Minggu ke-2: Halaman Ringkasan, Arsitektur, Konfigurasi Lingkungan Merevisi Bot

Minggu ke-3 - Menentukan daftar subproject (repo github bot) yang harus ditransfer ke dalam dokumentasi utama. - Menentukan cara kerja situs bot setelah transfer. - Menentukan {i>template<i} yang akan digunakan untuk mengatur info dalam repo ini. - Siapkan dokumentasi utama untuk transfer

Minggu ke-4: Repo Transfer bBot. Menyusun informasi sesuai dengan template yang ditentukan

Minggu ke-5: Transfer repo Hubot. Menyusun informasi sesuai dengan template yang ditentukan

Minggu ke-6: Repo Transfer Botkit. Menyusun informasi sesuai dengan template yang ditentukan

Minggu ke-7: Repo Transfer Rasa. Menyusun informasi sesuai dengan template yang ditentukan

Minggu ke-8: repo Transfer BotPress. Menyusun informasi sesuai dengan template yang ditentukan

Minggu ke-9: Penyelesaian struktur dan halaman dokumentasi utama setelah mentransfer semua sub-project bot

Minggu ke-10: Periksa konfigurasi JSDoc. Tentukan tempat untuk menyimpan artefak JSDoc. Mulai mendokumentasikan metode driver

Minggu ke-11: Selesai mendokumentasikan metode pengemudi

Minggu ke-12: Mengevaluasi hasil

PERINCIAN DETAIL PENCAPAIAN

PERIODE PENINJAUAN APLIKASI

Bagian pertama periode ini akan didedikasikan untuk memeriksa saluran komunitas dan kode sumber, serta menghubungi orang-orang yang berdedikasi pada proyek ini.

Bagian kedua dari periode ini akan difokuskan untuk memeriksa budaya kontribusi secara umum, memeriksa panduan kontribusi dan praktik terbaik. Inilah saatnya bagi kontribusi pertama untuk melihat cara kerja alurnya.

PENAWARAN KOMUNITAS

Kali ini akan dikhususkan untuk pemeriksaan yang lebih mendalam terhadap repositori dokumentasi beserta roadmap-nya. Berdasarkan informasi tersebut, titik lemah dapat diidentifikasi (misalnya bagian yang tidak lengkap atau tidak lengkap) yang dapat diperbaiki. Buat permintaan pull (jika memungkinkan) untuk mengisi kekosongan.

MINGGU 1 - MINGGU 2

Minggu pertama akan didedikasikan untuk komunikasi dengan mentor guna menyelaraskan dengan visi baru dokumentasi Bot. Informasi ini akan menjadi bagian dari dokumen yang direvisi yang bertujuan memberi pembaca gambaran umum tentang apa itu bot dan prinsip kerjanya.

Minggu kedua adalah tentang membuat konten untuk Halaman Beranda Bot baru sesuai dengan visi dan merevisi halaman Ringkasan, Arsitektur, Konfigurasi Lingkungan Bot.

Dokumen yang direvisi akan memiliki fokus yang lebih jelas di: - Developer baru yang ingin membuat bot sendiri - Developer [bot] profesional yang ingin mendesain/menulis kode/menguji bot menggunakan platform yang gratis dan mudah digunakan atau beradaptasi dengan bot yang ada dengan platform tersebut - Developer bot profesional dengan preferensi framework mereka yang ingin membuat bot untuk Rocket.Chat

Cakupan pekerjaannya adalah sebagai berikut:

  1. Hapus bagian yang redundan. Misalnya, bagian berikut membagikan informasi yang tumpang-tindih:
    • Bagaimana cara bot mengirim dan menerima pesan? Ringkasan Dalam Bot (https://rocket.chat/docs/bots/#how-do-bots-send-and-accept-messages)
    • Aliran Pesan di Arsitektur Bot (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Bicara dengan bot Anda di Membuat Pengguna Bot (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)

  2. Revisi bagian dan frasa di halaman Ringkasan Bot untuk mendeskripsikan ekosistem dan fungsi bot dengan jelas berdasarkan prinsip DRY.

    Merevisi bagian dan frasa tentang informasi ""di balik layar"":

    • Pengertian bot dari perspektif teknis
    • Komponen yang terdiri dari
    • Cara komponen-komponen ini bekerja sama

  3. Tulis panduan memulai cepat yang menjelaskan langkah-langkah yang diperlukan untuk membuat bot (dengan link ke ""Mengonfigurasi lingkungan bot"" sebagai bacaan lebih lanjut). Panduan ini akan ditempatkan di halaman Konfigurasi Lingkungan.

Dengan cara ini, developer akan memiliki visi yang jelas tentang sifat bot, dan apa yang dapat dilakukan bot. Setelah itu, developer akan dapat membuat bot pertamanya.

Hasil: Panduan pengenalan yang diperbarui dan mudah diikuti berisi informasi tentang ekosistem dan arsitektur bot.

MINGGU KE-3 - 9

Minggu 3 sampai 9 akan didedikasikan untuk penyatuan semua dokumen bot di seluruh repositori github dan transfer dokumen ini ke dokumentasi utama (https://rocket.chat/docs/bots/). Aktivitas ini dapat dibagi menjadi beberapa iterasi:

  1. Definisi

    Menentukan daftar sub-project bot yang harus dimigrasikan ke dokumentasi utama. Tentukan cara kerja situs bot setelah transfer (beberapa bot, bbot, misalnya (http://bbot.chat)) memiliki situs terpisah dengan dokumentasi selain github).

  2. Template

    Mendefinisikan dan membuat template (cara) untuk mengatur informasi dalam sub-project bot yang ditentukan pada langkah pertama. Template ini akan terlihat seperti berikut:

    a. Meng-clone repo

    b. Menginstal dependensi

    c. Mengonfigurasi bot

    d. Menjalankan bot

    e. Konfigurasi lanjutan

    f. Langkah lebih lanjut

    Perintah yang menyertakan beberapa {i>output<i} tidak umum (seperti ""jalankan bot"") harus disertai dengan presentasi langsung dari {i>output<i} tersebut menggunakan alat Lembar Istilah (https://neatsoftware.github.io/term-sheets/).

    Selain itu, agar tahap ""mulai cepat"" awal (langkah a - d) lebih jelas, semua langkah juga akan digabungkan dalam satu presentasi langsung.

    Untuk membuat pengguna baru merasa aman dari potensi kegagalan, contoh kode harus disediakan dengan lingkungan playground (menggunakan Glitch, sebagai bagian dari ekosistem Rocket Chat) tempat pendatang baru dapat chat dengan bot yang memiliki ""kode contoh"" di balik layar.

  3. Persiapan

    Menyiapkan dokumentasi utama untuk transfer. Ini termasuk membuat folder dan struktur halaman yang benar, serta menyesuaikan daftar isi sesuai dengan struktur tersebut.

    Struktur akhir akan terlihat seperti berikut:

    • Bot
      • Arsitektur Bot
      • Membuat Pengguna Bot
      • Mengonfigurasi Lingkungan Bot
      • Jalankan Bot
        • Bot bBot
        • Bot Hubot
        • Bot Botkit
        • Rasa Bot
        • Bot Botpress

  4. Migrasi

    Memigrasikan sub-project bot yang ditentukan ke dokumentasi utama satu per satu. Setiap dokumentasi bot akan memiliki halaman terpisah dengan sub-bagian seperti versi saat ini (misalnya menjalankan bBot).

    • Jalankan Bot
      • Bot bBot
      • Bot Hubot
      • Bot Botkit
      • Rasa Bot
      • Bot Botpress

  5. Organisasi

    Akan ada beberapa aktivitas:

    1. Mengatur informasi dari setiap repo bot github sesuai dengan template yang ditentukan pada langkah ke-2.
    2. Memindahkan komponen umum (misalnya variabel lingkungan) yang terkait dengan semua sub-project bot satu tingkat ke atas dalam hierarki dokumentasi utama dan sub-project link bot ke komponen ini
    3. Membuat contoh bot “hello world” untuk setiap framework yang didukung. Contoh ini akan digunakan sebagai bot “memulai” untuk Rocket.Chat.

Mengapa kebijakan ini penting? Kedelapan sub-project yang didukung oleh Rocket.Chat: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy, memiliki dokumen-dokumen yang tersebar dalam bentuk README developer. README ini tidak memiliki struktur sama sekali, berisi informasi usang tentang cara memulai, atau berisi terlalu banyak informasi (terkadang dengan tiga redundansi, seperti hubot (https://github.com/RocketChat/hubot-rocketchat) tentang cara menjalankan bot menggunakan Docker), serta tabel yang berisi variabel lingkungan.

Aspek ini membingungkan developer (sebagai pendatang baru) dengan tingkat detail yang luar biasa. Akibatnya, developer akan gagal mengaktifkan dan menjalankan bot hanya dengan beberapa perintah terminal.

Setelah transfer dan pengoptimalan selesai, repositori bot yang ada di github akan memiliki file README yang merujuk pada dokumentasi utama.

Hal ini akan memberikan manfaat berikut: - Struktur terpadu yang memudahkan developer memulai dengan bot baru - Satu sumber tepercaya untuk dokumentasi bot - Lebih mudah menemukan informasi yang diperlukan tentang bot apa pun berkat struktur terpadu

Hasil kerja: diatur di satu tempat (dokumentasi utama) petunjuk yang mudah diikuti tentang cara membuat, mengonfigurasi, dan menjalankan bot yang didukung oleh Rocket.Chat.

MINGGU KE-10

Minggu ini akan difokuskan untuk mengonfigurasi JSDoc (https://devdocs.io/jsdoc/) guna memaksimalkan nilai komentar inline. Hal ini mencakup:

  1. Memastikan bahwa JSDoc dikonfigurasi dengan benar guna mengurai komentar untuk metode driver (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver- methods)
  2. Instal postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) untuk membuat output HTML yang dihasilkan lebih eksplisit dan cocok untuk developer
  3. Menentukan lokasi tempat artefak dokumentasi JSDoc akan dipublikasikan
  4. Menjelaskan semua fungsi (di file dist/lib/driver.js) yang terkait dengan metode driver. Hal ini mencakup:
    • Menambahkan/mengedit deskripsi metode
    • Menambahkan/mengedit deskripsi parameter metode
    • Menambahkan/mengedit contoh permintaan metode, jika ada
    • Menambahkan/mengedit contoh respons metode, jika ada

Dokumentasi inline lebih mudah ditulis dan dikelola dari sudut pandang developer, dan mekanisme pembuatannya otomatis memungkinkan Anda untuk menyingkirkan dokumentasi statis yang dihosting di GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) yang harus diperbarui secara terpisah pada setiap perubahan dalam metode SDK.

MINGGU KE-11

Minggu ini akan difokuskan sepenuhnya untuk finalisasi penjelasan metode {i>driver<i}. Setelah selesai, deskripsi akan diuji keakuratan dan konsistensinya, lalu dokumentasi baru akan dipublikasikan.

MINGGU KE-12

Finalisasi pekerjaan yang telah selesai. Cek penerimaan.