Dự án Rocket.Chat

Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.

Tóm tắt dự án

Tổ chức nguồn mở:
Rocket.Chat
Người viết nội dung kỹ thuật:
Màu vàng
Tên dự án:
Tài liệu bot
Thời lượng dự án:
Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

TÓM TẮT DỰ ÁN

Bot trò chuyện là công nghệ tiên tiến của công nghệ ngày nay. Tỷ lệ tăng trưởng tổng thể rất lớn của phần mềm trò chuyện và bot, cùng với công nghệ nhận dạng lời nói và công nghệ tự động hoá ngày càng gia tăng, khiến cho nhu cầu phải tạo những tài liệu về bot dễ nắm bắt và sử dụng.

Việc có tài liệu đầy đủ và rõ ràng càng trở nên quan trọng hơn. Vì vậy, tài liệu hiện có về bot cần phải trở nên dễ truy cập và thao tác dễ hơn, cung cấp hướng dẫn từng bước thống nhất cho từng khung được hỗ trợ và các ví dụ bao quát. Ngoài ra, bạn cũng nên thu thập thông tin để loại bỏ những thông tin thừa và khó hiểu.

Mục tiêu của dự án là thu hẹp khoảng cách kiến thức và khuyến khích các nhà phát triển mới, ít kinh nghiệm hơn mang đến lợi ích của công nghệ tiên tiến cho đối tượng người dùng hào hứng. Họ có thể thực hiện việc này bằng cách cung cấp trải nghiệm đơn giản cho các trình tạo bot trong việc phát triển bot của riêng họ trong Rocket.Chat. Mục tiêu này là biến Rocket.Chat trở thành nền tảng nguồn mở được các nhà phát triển ưu tiên để đổi mới, sáng tạo và thử nghiệm ý tưởng bot trò chuyện, bất kể mục tiêu triển khai BOT là gì.

Vấn đề về dự án

Sau đây là danh sách các vấn đề quan trọng nhất liên quan đến tài liệu về bot:

  1. Thông tin chung không trực quan và không thân thiện về bot
  2. Các phần rải rác và thừa liên quan đến cấu trúc bot
  3. Những chi tiết hướng dẫn cách "bắt đầu" thiếu ngăn nắp mà không có một nguồn thông tin chính xác duy nhất
  4. Thiếu hướng dẫn hoặc cung cấp quá nhiều thông tin hướng dẫn
  5. Tài liệu về SDK bot ngầm ẩn và không rõ ràng

ĐỀ XUẤT DỰ ÁN

Theo mục tiêu của dự án và các vấn đề đã nêu ở trên, sau đây là danh sách các điểm cải tiến được đề xuất:

  1. Cập nhật tài liệu về bot. Để phần giới thiệu ban đầu mượt mà và nhất quán, bạn nên cập nhật dần các tài liệu sau đây và chuyển dần từ đơn giản sang phức tạp hơn:

    • Tổng quan về bot: https://rocket.chat/docs/bots/
    • Kiến trúc bot: https://rocket.chat/docs/bots/bots-structure/
    • Định cấu hình môi trường bot: https://rocket.chat/docs/bots/configure-bot-environment/
    • Trang chủ của bot: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Sắp xếp và hợp nhất tài liệu cài đặt bot. Tất cả các dự án phụ đều phải có một bộ hướng dẫn thống nhất hướng dẫn cách sao chép kho lưu trữ bot và cài đặt các phần phụ thuộc cần thiết, cách bắt đầu nhanh, cách làm việc với bot sau lần khởi chạy đầu tiên và cách triển khai.

  3. Sửa đổi bản trình bày tài liệu về SDK Rocket.Chat JS. Tài liệu SDK phải được tạo theo lập trình từ mã nguồn bằng các công cụ chuyên dụng. Điểm cải tiến này sẽ giúp bạn dễ đọc và không cần phải cập nhật tài liệu trên GitHub theo cách thủ công mỗi khi một phương thức (hoặc nội dung nào đó bên trong) thay đổi.

Diễn biến chính

Giai đoạn xem xét đơn đăng ký: Làm quen với cộng đồng và những người mà bạn muốn hợp tác. Tìm hiểu các phương pháp hay nhất và hướng dẫn về khoản đóng góp của cộng đồng. Thực hiện những đóng góp đầu tiên.

Gắn kết cộng đồng: Khám phá cộng đồng. Kiểm tra trạng thái hiện tại của tài liệu về bot. Xác định điểm yếu.

Tuần 1: Điều chỉnh cho phù hợp với các cố vấn về tầm nhìn mới của Bot. Tạo nội dung cập nhật cho Trang chủ bot mới theo tầm nhìn.

Tuần 2: Sửa đổi tổng quan về bot, cấu trúc, cấu hình của trang Môi trường

Tuần 3 – Xác định danh sách các dự án phụ (bot github repos) cần được chuyển vào tài liệu chính. – Xác định cách hoạt động của các trang web bot sau khi chuyển. – Xác định một mẫu dùng để sắp xếp thông tin trong các kho lưu trữ này. - Chuẩn bị tài liệu chính cho việc chuyển miền

Tuần 4: Chuyển kho lưu trữ bBot. Sắp xếp thông tin theo mẫu đã xác định

Tuần 5: Chuyển kho lưu trữ Hubot. Sắp xếp thông tin theo mẫu đã xác định

Tuần 6: Chuyển kho lưu trữ Botkit. Sắp xếp thông tin theo mẫu đã xác định

Tuần 7: Chuyển kho lưu trữ Rasa. Sắp xếp thông tin theo mẫu đã xác định

Tuần 8: Chuyển kho lưu trữ BotPress. Sắp xếp thông tin theo mẫu đã xác định

Tuần 9: Hoàn thiện các trang và cấu trúc tài liệu chính sau khi chuyển tất cả dự án phụ của bot

Tuần 10: Kiểm tra cấu hình JSDoc. Xác định nơi lưu trữ cấu phần phần mềm JSDoc. Bắt đầu ghi lại phương thức của trình điều khiển

Tuần 11: Hoàn tất việc ghi lại phương thức của người lái xe

Tuần 12: Đánh giá kết quả

THÔNG TIN CHI TIẾT VỀ CÁC MỐC QUAN TRỌNG

THỜI GIAN XEM XÉT ỨNG DỤNG

Phần đầu của giai đoạn này sẽ được dành để kiểm tra các kênh cộng đồng và mã nguồn, đồng thời liên hệ với những người chuyên trách về dự án.

Phần thứ hai của giai đoạn này sẽ tập trung vào việc kiểm tra văn hoá đóng góp nói chung, xem xét các hướng dẫn về việc đóng góp và các phương pháp hay nhất. Đây sẽ là lần đóng góp đầu tiên để tìm hiểu cách hoạt động của quy trình.

KẾT NỐI CỘNG ĐỒNG

Lần này chúng ta sẽ tìm hiểu kỹ hơn về kho lưu trữ tài liệu cùng với lộ trình của kho lưu trữ này. Dựa trên thông tin đó, có thể xác định những điểm yếu (ví dụ: các phần chưa hoàn chỉnh hoặc bị thiếu) có thể cải thiện. Tạo yêu cầu kéo (nếu có thể) để bổ sung dữ liệu còn thiếu.

TUẦN 1 – TUẦN 2

Tuần đầu tiên sẽ dành cho việc trao đổi với những người cố vấn nhằm điều chỉnh tầm nhìn mới cho tài liệu về Bot. Thông tin này sẽ nằm trong tài liệu sửa đổi nhằm cung cấp cho độc giả thông tin tổng quan chung về bot là gì cũng như nguyên tắc hoạt động của bot.

Tuần thứ hai sẽ là về việc tạo nội dung cho Trang chủ bot mới theo tầm nhìn và sửa đổi các trang Tổng quan về bot, Cấu trúc, Cấu hình của môi trường.

Tài liệu sửa đổi sẽ tập trung rõ hơn vào: – Nhà phát triển mới muốn tạo bot của riêng mình – Nhà phát triển [bot] chuyên nghiệp muốn thiết kế/lập trình/kiểm thử bot bằng nền tảng miễn phí và dễ sử dụng hoặc thích ứng với bot hiện có trên nền tảng đó – Nhà phát triển bot chuyên nghiệp có lựa chọn ưu tiên về khung muốn tạo bot cho Rocket.Chat

Phạm vi công việc sẽ như sau:

  1. Xoá các mục dư thừa. Ví dụ: các phần sau đây chia sẻ thông tin chồng chéo:
    • Các bot gửi và nhận tin nhắn bằng cách nào? Trong phần Tổng quan về bot (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Luồng tin nhắn trong Kiến trúc bot (https://rocket.chat/docs/bots/bots-structure/#message-streams)
    • Trò chuyện với bot của bạn trong phần Tạo người dùng bot (https://rocket.chat/docs/bots/creating-bot-users/#nói-to-your-bot)

  2. Sửa đổi các phần và cụm từ trên trang Tổng quan về bot để mô tả rõ ràng hệ sinh thái và chức năng của bot theo nguyên tắc DRY.

    Sửa lại các phần và cụm từ về thông tin ""nâng cao"":

    • Bot là gì từ góc độ kỹ thuật
    • Thành phần của gói này
    • Cách các thành phần này hoạt động cùng nhau

  3. Viết hướng dẫn bắt đầu nhanh để mô tả các bước cần thiết để tạo bot (kèm theo đường liên kết đến phần ""Định cấu hình môi trường bot"" để đọc thêm). Hướng dẫn này sẽ được đặt trong trang Cấu hình môi trường.

Bằng cách này, nhà phát triển sẽ có tầm nhìn rõ ràng về bản chất của bot và những gì bot có khả năng thực hiện. Từ thời điểm đó, nhà phát triển sẽ có thể tạo bot đầu tiên của họ.

Thành phẩm: Hướng dẫn đã được sửa đổi, dễ làm theo và có thông tin về hệ sinh thái và cấu trúc bot.

TUẦN 3 – 9

Tuần 3 đến tuần 9 sẽ được dành riêng cho việc hợp nhất tất cả các tài liệu bot trên các kho lưu trữ github và chuyển các tài liệu này sang tài liệu chính (https://rocket.chat/docs/bots/). Những hoạt động này có thể được chia thành nhiều lần lặp lại:

  1. Định nghĩa

    Xác định danh sách các dự án bot phụ cần di chuyển sang tài liệu chính. Xác định cách hoạt động của các trang web bot sau khi chuyển (một số bot, bbot, ví dụ (http://bbot.chat)) có các trang web riêng biệt với tài liệu ngoài github).

  2. Mẫu

    Xác định và tạo mẫu (một cách) để sắp xếp thông tin trong các dự án phụ của bot được xác định ở bước đầu tiên. Mẫu này có thể giống như sau:

    a. Sao chép kho lưu trữ

    b. Cài đặt phần phụ thuộc

    c. Định cấu hình bot

    d. Chạy bot

    e. Cấu hình nâng cao

    f. Các bước khác

    Các lệnh có chứa một số kết quả không quan trọng (như ""chạy bot"") phải đi kèm với bản trình bày trực tiếp của kết quả đó bằng công cụ Bảng thuật ngữ (https://neatsoftware.github.io/term-sheets/).

    Hơn nữa, để giúp giai đoạn ""bắt đầu nhanh"" ban đầu (các bước a - d) trở nên rõ ràng hơn, tất cả các bước cũng sẽ được kết hợp trong một bài thuyết trình trực tiếp.

    Để giúp người dùng mới cảm thấy an toàn trước các thất bại có thể xảy ra, bạn nên cung cấp các ví dụ về mã trong môi trường sân chơi (sử dụng Glitch, như một phần của hệ sinh thái Rocket Chat), nơi người chơi mới có thể trò chuyện với các bot có ""mã ví dụ"" nâng cao.

  3. Chuẩn bị

    Chuẩn bị giấy tờ chính để chuyển miền. Điều này bao gồm việc tạo thư mục và cấu trúc trang thích hợp, cũng như điều chỉnh mục lục theo cấu trúc đó.

    Cấu trúc hoàn thiện có thể có dạng như sau:

    • Bot
      • Kiến trúc bot
      • Tạo người dùng bot
      • Định cấu hình môi trường bot
      • Chạy bot
        • Bot bBot
        • Bot Hubot
        • Botkit
        • Bot Rasa
        • Botpress

  4. Di chuyển

    Di chuyển từng dự án bot đã xác định sang tài liệu chính. Mỗi phần tài liệu về bot sẽ có một trang riêng với các phần phụ như phiên bản hiện tại (ví dụ: chạy bBot).

    • Chạy bot
      • Bot bBot
      • Bot Hubot
      • Botkit
      • Bot Rasa
      • Botpress

  5. Tổ chức

    Sẽ có một số hoạt động:

    1. Sắp xếp thông tin từ mỗi kho lưu trữ GitHub cho bot theo mẫu được xác định ở bước 2.
    2. Di chuyển các thành phần chung (ví dụ: biến môi trường) liên quan đến tất cả các dự án phụ bot lên một cấp trong hệ thống phân cấp của tài liệu chính và liên kết các dự án bot với các thành phần này
    3. Tạo ví dụ về bot "xin chào thế giới" cho từng khung được hỗ trợ. Ví dụ này sẽ được dùng làm bot "bắt đầu" cho Rocket.Chat.

Tại sao điều này quan trọng? Cả 8 dự án phụ do Rocket.Chat hỗ trợ: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy đều có các tài liệu rải rác dưới dạng README của nhà phát triển. Những README này hoàn toàn không có cấu trúc, chứa thông tin lỗi thời về cách bắt đầu hoặc chứa quá nhiều thông tin (đôi khi có sự dư thừa gấp 3 lần, như hubot (https://github.com/RocketChat/hubot-rocketchat) về cách chạy bot bằng Docker), cũng như bảng chứa các biến môi trường.

Những khía cạnh này khiến nhà phát triển (là người mới chơi) nhầm lẫn với mức độ chi tiết vô cùng lớn. Do đó, chỉ với một vài lệnh trong dòng lệnh, nhà phát triển sẽ không thể thiết lập và chạy bot.

Sau khi hoàn tất quá trình chuyển và tối ưu hoá, kho lưu trữ bot hiện có trên github sẽ có các tệp README tham chiếu đến tài liệu chính.

Điều này sẽ mang lại những lợi ích sau: – Một cấu trúc hợp nhất giúp các nhà phát triển bắt đầu sử dụng bot mới dễ dàng hơn – Một nguồn đáng tin cậy duy nhất cho tài liệu về bot – Tìm thấy thông tin cần thiết về bất kỳ bot nào dễ dàng hơn nhờ cấu trúc hợp nhất

Thành phẩm: Được sắp xếp trong một nơi duy nhất (tài liệu chính) hướng dẫn dễ thực hiện về cách tạo, định cấu hình và chạy bot do Rocket.Chat hỗ trợ.

TUẦN 10

Tuần này sẽ dành riêng cho việc định cấu hình JSDoc (https://devdocs.io/jsdoc/) nhằm tối đa hoá giá trị của các nhận xét cùng dòng. Vấn đề này bao gồm:

  1. Đảm bảo rằng JSDoc được định cấu hình đúng cách để phân tích cú pháp nhận xét cho phương thức của trình điều khiển (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-–
  2. Cài đặt postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) để làm cho kết quả HTML kết quả rõ ràng và thân thiện với nhà phát triển hơn
  3. Xác định nơi sẽ xuất bản các cấu phần phần mềm của tài liệu JSDoc
  4. Mô tả tất cả tệp hàm (trong dist/lib/driver.js) liên quan đến phương thức của trình điều khiển. Trong đó có:
    • Thêm/chỉnh sửa phần mô tả của phương thức
    • Thêm/chỉnh sửa nội dung mô tả các tham số của phương thức
    • Thêm/chỉnh sửa ví dụ về yêu cầu phương thức, nếu có
    • Thêm/chỉnh sửa ví dụ về câu trả lời của phương thức (nếu có)

Tài liệu cùng dòng dễ viết và duy trì hơn từ góc nhìn của nhà phát triển, đồng thời cơ chế tự động tạo tài liệu này cho phép bạn loại bỏ tài liệu tĩnh được lưu trữ trên GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods), phải được cập nhật riêng trên mỗi thay đổi trong phương thức SDK.

TUẦN 11

Tuần này sẽ dành toàn bộ nội dung cho phần mô tả phương pháp dành cho trình điều khiển. Sau khi hoàn thành, nội dung mô tả sẽ được kiểm tra tính chính xác và nhất quán, sau đó tài liệu mới sẽ được xuất bản trên toàn thế giới.

TUẦN 12

Hoàn tất công việc đã hoàn thành. Kiểm tra chấp nhận.