Dự án Rocket.Chat

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

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

Mô tả dự án

TÓM TẮT DỰ ÁN

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

Việc có tài liệu toàn diện và rõ ràng trở nên quan trọng hơn bao giờ hết, vì vậy, tài liệu về bot hiện có cần được dễ dàng truy cập và điều hướng hơn, cung cấp hướng dẫn từng bước hợp nhất cho từng khung được hỗ trợ và các ví dụ mở rộng. Ngoài ra, bạn cũng nên sắp xếp lại để loại bỏ 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 mang lại lợi ích của công nghệ tiên tiến cho một đối tượng hào hứng. Điều này có thể được thực hiện bằng cách cung cấp cho người tạo bot một trải nghiệm đơn giản trong việc phát triển bot của riêng họ trong tên lửa. Mục tiêu này nhằm biến Rocket.Chat thành nền tảng nguồn mở ưu tiên để các nhà phát triển này đổi mới, tạo và thử nghiệm các ý tưởng về chatbot của họ – bất kể mục tiêu triển khai BOT cuối cùng 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 về bot không trực quan và không thân thiện
  2. Các phần rải rác và dư thừa liên quan đến kiến trúc bot
  3. Các phần hướng dẫn "bắt đầu" không được sắp xếp hợp lý và không có nguồn đáng tin cậy
  4. Thiếu hướng dẫn hoặc hướng dẫn quá chi tiết
  5. Tài liệu về SDK bot ngầm ẩn và mơ hồ

ĐỀ XUẤT DỰ ÁN

Dựa trên 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 diễn ra suôn sẻ và nhất quán, bạn nên cập nhật các tài liệu sau đây theo hướng chuyển đổi dần từ đơn giản đến phức tạp hơn:

    • Tổng quan về bot: https://rocket.chat/docs/bots/
    • Cấu trúc bot: https://rocket.chat/docs/bots/bots-structured/
    • Đị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ả dự án phụ phải có một bộ hướng dẫn thống nhất về cách sao chép kho lưu trữ bot và cài đặt các phần phụ thuộc bắt buộc, cách bắt đầu nhanh, cách làm việc với bot sau lần chạy đầu tiên và cách triển khai bot.

  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 phương thức lập trình từ mã nguồn bằng các công cụ chuyên biệt. Điểm cải tiến này sẽ giúp tài liệu 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 phương thức đó) thay đổi.

Diễn biến chính

Thời gian xem xét đơn đăng ký: Làm quen với cộng đồng và những người sẽ làm việc cùng bạn. Tìm hiểu hướng dẫn và các phương pháp hay nhất về việc đóng góp cho cộng đồng. Đóng góp những nội dung đầ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: Thống nhất 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ủ mới của Bots theo tầm nhìn.

Tuần 2: Xem lại phần Tổng quan về bot, Kiến trúc, Cấu hình của các trang Môi trường

Tuần 3 – Xác định danh sách các dự án phụ (kho lưu trữ GitHub của bot) cần được chuyển vào tài liệu chính. – Xác định cách hoạt động của trang web bot sau khi chuyển. – Xác định mẫu sẽ được 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 để 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ấu trúc và các trang 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ác cấu phần phần mềm JSDoc. Bắt đầu ghi lại các phương thức trình điều khiển

Tuần 11: Hoàn tất việc ghi lại các phương thức trình điều khiển

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

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

THỜI HẠN XEM XÉT ĐƠN ĐĂNG KÝ

Phần đầu tiên của khoảng thời gian này sẽ 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 tận tâm với dự án.

Phần thứ hai của khoảng thời gian này sẽ dành để kiểm tra văn hoá đóng góp nói chung, xem xét hướng dẫn đóng góp và các phương pháp hay nhất. Đây sẽ là lúc để những nội dung đóng góp đầu tiên được xem cách quy trình hoạt động.

GẮN KẾT CỘNG ĐỒNG

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

TUẦN 1 – TUẦN 2

Tuần đầu tiên sẽ dành cho hoạt động trao đổi thông tin với cố vấn nhằm thống nhất tầm nhìn mới về tài liệu của Bot. Thông tin này sẽ nằm trong các tài liệu sửa đổi nhằm cung cấp cho độc giả cái nhìn tổng quan chung về bot là gì cũng như các 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, Kiến trúc, Cấu hình của Môi trường về Bot.

Tài liệu sửa đổi sẽ tập trung rõ ràng 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 một nền tảng miễn phí và dễ sử dụng hoặc điều chỉnh bot hiện có cho phù hợp với nền tảng đó - Nhà phát triển bot chuyên nghiệp có lựa chọn ưu tiên về khung và muốn tạo bot cho Rocket.Chat

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

  1. Xoá các phần thừa. Ví dụ: các phần sau đây có thông tin trùng lặp:
    • 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 cấu trúc Bot (https://rocket.chat/docs/bots/bots-Architect/#message-streams)
    • Trò chuyện với bot trong phần Tạo người dùng bot (https://rocket.chat/docs/bots/creating-bot-users/#talk-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 đổi các phần và cụm từ về thông tin ""phần bên trong"":

    • Khái niệm về bot theo góc độ kỹ thuật
    • Nền tảng này bao gồm những thành phần nào
    • 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 (có đườ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ó một tầm nhìn rõ ràng về bản chất của bot và những gì bot có thể làm. Từ đó, nhà phát triển có thể tạo bot đầu tiên của mình.

Sản phẩm: Hướng dẫn giới thiệu đã sửa đổi, dễ hiểu, cung cấp thông tin về hệ sinh thái và cấu trúc của bot.

TUẦN 3 – 9

Từ tuần thứ 3 đến thứ 9 sẽ 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/). Bạn có thể chia các hoạt động này thành một số lần lặp:

  1. Định nghĩa

    Xác định danh sách các dự án phụ của bot cần di chuyển sang tài liệu chính. Xác định cách các trang web bot sẽ hoạt động sau khi chuyển (ví dụ: một số bot, bbot (http://bbot.chat)) có các trang web riêng kèm theo 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 con bot được xác định ở bước đầu tiên. Mẫu này có thể có dạ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 tiếp theo

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

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

    Để giúp người mới cảm thấy an toàn trước những lỗi tiềm ẩn, 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, một phần của hệ sinh thái Rocket Chat) để người mới có thể trò chuyện với các bot có ""mã ví dụ"".

  3. Chuẩn bị

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

    Cấu trúc cuối cùng có thể có dạng như sau:

    • Bot
      • Cấu 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
        • Hubot Bot
        • Bot Botkit
        • Bot Rasa
        • Bot Botpress

  4. Di chuyển

    Di chuyển từng dự án phụ của 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 mục phụ như phiên bản hiện tại (ví dụ: chạy bBot).

    • Chạy bot
      • Bot bBot
      • Hubot Bot
      • Bot Botkit
      • Bot Rasa
      • Bot 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 của bot theo mẫu được xác định ở bước 2.
    2. Di chuyển các thành phần phổ biến (ví dụ: biến môi trường) liên quan đến tất cả dự án phụ của bot lên một cấp trong hệ phân cấp của tài liệu chính và liên kết các dự án phụ của 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? Tất cả 8 dự án phụ do Rocket.Chat hỗ trợ: alexa, hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy đều có tài liệu rải rác dưới dạng README dành cho nhà phát triển. Các 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ó cơ chế dự phòng gấp ba, 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) bối rối với mức độ chi tiết cực kỳ cao. Do đó, nhà phát triển sẽ không thể khởi động và chạy bot chỉ bằng một vài lệnh dòng lệnh.

Sau khi hoàn tất quá trình chuyển và tối ưu hoá, các kho lưu trữ bot hiện có trong 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: - Cấu trúc hợp nhất giúp nhà phát triển dễ dàng bắt đầu sử dụng bot mới - Nguồn thông tin chính xác duy nhất cho tài liệu về bot - Dễ dàng tìm thấy thông tin cần thiết về bất kỳ bot nào nhờ cấu trúc hợp nhất

Sản 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ễ hiểu về cách tạo, định cấu hình và chạy các bot được 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/) để tối đa hoá giá trị của các nhận xét cùng dòng. Nội dung như vậ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 các nhận xét cho phương thức trình điều khiển (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
  2. Cài đặt postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme) để làm cho kết quả đầu ra HTML rõ ràng hơn và thân thiện với nhà phát triển
  3. Xác định vị trí phát hành cấu phần phần mềm tài liệu JSDoc
  4. Mô tả tất cả các hàm (trong tệp dist/lib/driver.js) liên quan đến các phương thức trình điều khiển. Trong đó có:
    • Thêm/chỉnh sửa nội dung mô tả phương thức
    • Thêm/chỉnh sửa nội dung mô tả về tham số phương thức
    • Thêm/chỉnh sửa ví dụ về các yêu cầu phương thức (nếu có)
    • Thêm/chỉnh sửa ví dụ về phản hồi phương thức (nếu có)

Tài liệu nội tuyến dễ viết và duy trì hơn theo quan điểm của nhà phát triển, đồng thời cơ chế tự động tạo của 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) mà bạn phải cập nhật riêng cho mỗi thay đổi trong các phương thức SDK.

TUẦN 11

Tuần này sẽ dành trọn vẹn cho việc hoàn tất việc mô tả các phương thức trình điều khiển. Sau khi hoàn tất, nội dung mô tả sẽ được kiểm tra độ chính xác và tính nhất quán, sau đó tài liệu mới sẽ được phát hành 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.