Project Rocket.Chat

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

Ringkasan project

Organisasi open source:
Rocket.Chat
{i>Technical writer <i}(Penulis teknis):
Pak Gold
Nama proyek:
Dokumen Bot
Durasi project:
Durasi standar (3 bulan)

Project description

RINGKASAN PROJECT

Chatbot adalah teknologi canggih saat ini. Rasio pertumbuhan keseluruhan yang sangat besar dalam software dan bot chat, serta pengenalan ucapan dan otomatisasi yang meningkat, menentukan perlunya membuat dokumentasi bot yang mudah dipahami dan digunakan.

Memiliki dokumentasi yang komprehensif dan jelas menjadi semakin penting, sehingga dokumentasi bot yang ada harus lebih mudah diakses dan dijelajahi, harus memberikan petunjuk langkah demi langkah terpadu untuk setiap framework yang didukung, dan contoh yang luas. Selain itu, informasi harus ditata agar tidak ada informasi yang berlebihan dan sulit dipahami.

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

Masalah Project

Berikut adalah daftar masalah paling penting yang terkait dengan dokumentasi bot:

  1. Informasi umum tentang bot yang tidak intuitif dan tidak mudah dipahami
  2. Bagian yang tersebar dan redundan terkait arsitektur bot
  3. Bagian-bagian petunjuk panduan "memulai" yang tidak teratur tanpa satu sumber tepercaya
  4. Kurangnya petunjuk atau tingkat detail petunjuk yang berlebihan
  5. Dokumentasi Bot SDK yang implisit dan tidak jelas

PROPOSAL PROJECT

Sesuai dengan sasaran project, dan masalah yang diuraikan di atas, berikut adalah daftar peningkatan yang diusulkan:

  1. Memperbarui dokumen bot. Agar pengantar awal berjalan lancar dan konsisten, dokumen berikut harus diperbarui dengan peralihan bertahap dari sederhana ke lebih kompleks:

    • Ringkasan Bot: https://rocket.chat/docs/bots/
    • Arsitektur Bot: https://rocket.chat/docs/bots/bots- Visualization/
    • 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 bekerja dengan bot setelah peluncuran pertama, dan cara men-deploy-nya.

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

Linimasa

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

Community Bonding: Jelajahi komunitas. Periksa status dokumentasi bot saat ini. Identifikasi titik lemah.

Minggu ke-1: Menyelaraskan dengan mentor tentang visi baru Bot. Buat konten yang diperbarui untuk Halaman Beranda Bot baru sesuai dengan visi.

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

Minggu ke-3 - Menentukan daftar sub-project (repositori github bot) yang harus ditransfer ke dokumentasi utama. - Tentukan cara kerja situs bot setelah transfer. - Menentukan template yang akan digunakan untuk mengatur info dalam repositori ini. - Menyiapkan dokumentasi utama untuk transfer

Minggu ke-4: Mentransfer repo bBot. Mengatur informasi sesuai dengan template yang ditentukan

Minggu ke-5: Mentransfer repo Hubot. Mengatur informasi sesuai dengan template yang ditentukan

Minggu ke-6: Mentransfer repo Botkit. Mengatur informasi sesuai dengan template yang ditentukan

Minggu ke-7: Mentransfer repo Rasa. Mengatur informasi sesuai dengan template yang ditentukan

Minggu ke-8: Mentransfer repo BotPress. Mengatur informasi sesuai dengan template yang ditentukan

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

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

Minggu ke-11: Menyelesaikan dokumentasi metode driver

Minggu ke-12: Mengevaluasi hasil

PERINCIAN PENCAPAIAN MENDETAIL

PERIODE PENINJAUAN APLIKASI

Bagian pertama dari periode ini akan dikhususkan untuk memeriksa saluran komunitas dan kode sumber serta menghubungi orang-orang yang berdedikasi untuk project ini.

Bagian kedua dari periode ini akan dikhususkan untuk memeriksa budaya kontribusi secara umum, memeriksa panduan kontribusi, dan praktik terbaik. Ini akan menjadi waktu untuk kontribusi pertama untuk melihat cara kerja alur.

PENGHUBUNGAN KOMUNITAS

Kali ini akan difokuskan untuk mempelajari repositori dokumentasi secara lebih mendalam beserta roadmap-nya. Berdasarkan informasi tersebut, Anda dapat mengidentifikasi titik lemah (misalnya, bagian yang tidak lengkap atau tidak ada) yang dapat ditingkatkan. Buat permintaan pull (jika memungkinkan) untuk mengisi kesenjangan.

MINGGU 1 - MINGGU 2

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

Minggu kedua akan membahas pembuatan 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 pada: - Developer baru yang ingin membuat bot mereka sendiri - Developer [bot] profesional yang ingin mendesain/membuat kode/menguji bot mereka menggunakan platform gratis dan mudah digunakan atau beradaptasi dengan bot yang ada ke 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 berlebihan. Misalnya, bagian berikut memiliki informasi yang tumpang-tindih:
    • Bagaimana cara bot mengirim dan menerima pesan? Di Ringkasan Bot (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Aliran Pesan dalam 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. Merevisi bagian dan frasa halaman Ringkasan Bot agar dapat menjelaskan ekosistem dan fungsi bot dengan jelas dengan mengikuti prinsip DRY.

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

    • Pengertian bot dari perspektif teknis
    • Komponen yang menyusunnya
    • Cara kerja komponen-komponen ini

  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 mampu dilakukan bot. Dari titik tersebut, developer akan dapat membuat bot pertamanya.

Hasil: Panduan pengantar yang direvisi dan mudah diikuti dengan informasi tentang ekosistem dan arsitektur bot.

MINGGU 3 - 9

Minggu ke-3 hingga ke-9 akan dikhususkan untuk penyatuan semua dokumen bot di seluruh repositori GitHub dan mentransfer 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, misalnya bbot (http://bbot.chat)) memiliki situs terpisah dengan dokumentasi selain github).

  2. Template

    Menentukan dan membuat template (cara) untuk mengatur informasi dalam sub-project bot yang ditentukan pada langkah ke-1. Template ini mungkin terlihat seperti berikut:

    a. Meng-clone repo

    b. Menginstal dependensi

    c. Mengonfigurasi bot

    d. Menjalankan bot

    e. Konfigurasi lanjutan

    f. Langkah selanjutnya

    Perintah yang menyertakan beberapa output non-trivial (seperti ""jalankan bot"") harus disertai dengan presentasi langsung output tersebut menggunakan alat Term Sheets (https://neatsoftware.github.io/term-sheets/).

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

    Agar pendatang 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 melakukan chat dengan bot yang memiliki ""kode contoh"" di balik layar.

  3. Persiapan

    Menyiapkan dokumentasi utama untuk transfer. Hal ini mencakup pembuatan folder dan struktur halaman yang tepat, serta menyesuaikan daftar isi sesuai dengan struktur tersebut.

    Struktur akhirnya mungkin terlihat seperti berikut:

    • Bot
      • Arsitektur Bot
      • Membuat Pengguna Bot
      • Mengonfigurasi Lingkungan Bot
      • Menjalankan Bot
        • Bot bBot
        • Bot Hubot
        • Bot Botkit
        • Bot Rasa
        • 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).

    • Menjalankan Bot
      • Bot bBot
      • Bot Hubot
      • Bot Botkit
      • Bot Rasa
      • Bot Botpress

  5. Organisasi

    Akan ada beberapa aktivitas:

    1. Mengatur informasi dari setiap repo github bot 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 menautkan sub-project bot ke komponen ini
    3. Membuat contoh bot “halo dunia” untuk setiap framework yang didukung. Contoh ini akan digunakan sebagai bot “mulai” untuk Rocket.Chat.

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

Aspek-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 ke dokumentasi utama.

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

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

MINGGU KE-10

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

  1. Memastikan JSDoc dikonfigurasi dengan benar untuk 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 mudah digunakan developer
  3. Menentukan tempat publikasi artefak dokumentasi JSDoc
  4. Menjelaskan semua file fungsi (di 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 perspektif developer, dan mekanisme pembuatan otomatisnya memungkinkan Anda menghapus 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 sepenuhnya dikhususkan untuk penyelesaian deskripsi metode driver. Setelah selesai, deskripsi akan diuji akurasi dan konsistensinya, lalu dokumentasi baru akan dipublikasikan ke seluruh dunia.

MINGGU KE-12

Penyelesaian pekerjaan yang telah selesai. Cek penerimaan.