Проект Rocket.Chat

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:
Rocket.Чат
Технический писатель:
Мистер Голд
Название проекта:
Документация по боту
Длина проекта:
Стандартная продолжительность (3 месяца)

Описание Проекта

РЕЗЮМЕ ПРОЕКТА

Чат-боты находятся на переднем крае современных технологий. Огромные общие темпы роста программного обеспечения для чатов и ботов, а также растущая популярность распознавания речи и автоматизации диктуют необходимость создания документации по ботам, которую легко понять и использовать.

Наличие всеобъемлющей и понятной документации становится еще более важным, поэтому необходимо упростить доступ к существующей документации по ботам и навигации, предоставить унифицированные пошаговые инструкции для каждой поддерживаемой платформы и подробные примеры. Также его следует привести в порядок, чтобы избавиться от лишней и трудной для понимания информации.

Цель проекта — восполнить пробел в знаниях и побудить новых, менее опытных разработчиков донести преимущества передовых технологий до восторженной аудитории. Этого можно добиться, предоставив разработчикам ботов упрощенный опыт разработки собственных ботов в Rocket.Chat. Эта цель направлена ​​на то, чтобы сделать Rocket.Chat предпочтительной платформой с открытым исходным кодом для этих разработчиков, чтобы они могли внедрять инновации, создавать и тестировать свои идеи чат-ботов - независимо от конечной цели развертывания BOT.

Проблемы проекта

Ниже приведен список наиболее важных вопросов, связанных с документацией по ботам:

  1. Неинтуитивная и недружелюбная общая информация о ботах
  2. Разрозненные и избыточные разделы, связанные с архитектурой ботов.
  3. Беспорядочные фрагменты инструкций по началу работы, не имеющие единого источника истины.
  4. Отсутствие инструкций или чрезмерная детализация инструкций.
  5. Неявная и расплывчатая документация Bot SDK.

ПРОЕКТНОЕ ПРЕДЛОЖЕНИЕ

В соответствии с целью проекта и проблемами, изложенными выше, ниже приводится список предлагаемых улучшений:

  1. Обновите документацию по боту. Чтобы сделать первоначальное внедрение плавным и последовательным, следующие документы следует обновлять с постепенным переходом от простого к более сложному:

    • Обзор ботов: https://rocket.chat/docs/bots/
    • Архитектура ботов: https://rocket.chat/docs/bots/bots-architecture/
    • Настройка среды бота: https://rocket.chat/docs/bots/configure-bot-environment/
    • Домашняя страница ботов: https://github.com/RocketChat/rocketchat.github.io/pull/

  2. Организуйте и унифицируйте документацию по установке ботов. Все подпроекты должны иметь единый набор инструкций о том, как клонировать репозиторий бота и установить необходимые зависимости, как быстро начать работу, как работать с ботом после первого запуска и как его развернуть.

  3. Пересмотреть презентацию документации Rocket.Chat JS SDK. Документация SDK должна создаваться программно из исходного кода с использованием специализированных инструментов. Это улучшение повысит читабельность и устранит необходимость обновлять документ на Github вручную каждый раз, когда изменяется метод (или что-то внутри него).

ГРАФИК

Период рассмотрения заявки: познакомьтесь с сообществом и людьми, с которыми можно работать. Изучите руководства и лучшие практики по вкладу сообщества. Сделайте первые взносы.

Связывание сообщества: исследуйте сообщество. Проверьте текущее состояние документации по боту. Выявить слабые места.

Неделя 1: Обсудите с наставниками новое видение ботов. Создайте обновленный контент для новой домашней страницы ботов в соответствии с видением.

Неделя 2: пересмотр страниц обзора ботов, архитектуры и настройки среды.

Неделя 3 — Определите список подпроектов (репозиториев ботов на GitHub), которые следует перенести в основную документацию. - Определите, как должны работать сайты-боты после переноса. - Определите шаблон, который будет использоваться для организации информации в этих репозиториях. - Подготовить основную документацию для перевода

Неделя 4: Перенос репозитория bBot. Организовать информацию в соответствии с заданным шаблоном

Неделя 5: Перенос репозитория Hubot. Организовать информацию в соответствии с заданным шаблоном

Неделя 6: Перенос репозитория Botkit. Организовать информацию в соответствии с заданным шаблоном

Неделя 7: Перенос репо Rasa. Организовать информацию в соответствии с заданным шаблоном

Неделя 8: Перенос репозитория BotPress. Организовать информацию в соответствии с заданным шаблоном

Неделя 9: Доработка основной структуры и страниц документации после переноса всех подпроектов бота.

Неделя 10: Проверьте конфигурацию JSDoc. Определите место для хранения артефактов JSDoc. Начать документировать методы драйвера

Неделя 11. Завершение документирования методов драйвера.

Неделя 12: Оценка результатов

ПОДРОБНАЯ РАЗБИВКА ЭТАПОВ

ПЕРИОД РАССМОТРЕНИЯ ЗАЯВЛЕНИЯ

Первая часть периода будет посвящена проверке каналов сообщества и исходного кода, а также общению с людьми, которые преданы проекту.

Вторая часть периода будет посвящена проверке культуры вкладов в целом, изучению руководств по вкладам и передового опыта. Это будет время для первых взносов, чтобы увидеть, как работает этот поток.

СВЯЗЬ СООБЩЕСТВА

Это время будет посвящено более глубокому изучению хранилища документации и его дорожной карты. На основе этой информации можно будет выявить слабые места (например, незавершенные или недостающие детали), которые можно улучшить. Создавайте запросы на включение (там, где это возможно), чтобы заполнить пробелы.

НЕДЕЛЯ 1 – НЕДЕЛЯ 2

Первая неделя будет посвящена общению с наставниками для согласования нового видения документации по ботам. Эта информация станет частью пересмотренных документов, призванных дать читателям общее представление о том, что такое бот и принципы его работы.

Вторая неделя будет посвящена созданию контента для новой домашней страницы ботов в соответствии с видением и пересмотру страниц «Обзор ботов», «Архитектура», «Конфигурация среды».

Пересмотренные документы будут более четко ориентированы на: - Новых разработчиков, которые хотят создать своего собственного бота - Профессиональных разработчиков [ботов], которые хотят проектировать/кодировать/тестировать своих ботов, используя бесплатную и простую в использовании платформу или адаптироваться к своим существующие боты для этой платформы — профессиональные разработчики ботов со своими предпочтениями в платформе, которые хотят создавать ботов для Rocket.Chat.

Объем работ будет следующий:

  1. Удалите лишние разделы. Например, следующие разделы содержат дублирующую информацию:
    • Как боты отправляют и получают сообщения? В обзоре ботов (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
    • Потоки сообщений в архитектуре ботов (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
    • Поговорите со своим ботом в разделе «Создание пользователей-ботов» (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot).

  2. Пересмотрите разделы и фразы на странице «Обзор ботов», чтобы они четко описывали экосистему и функциональность ботов в соответствии с принципом DRY.

    Повторить разделы и фразы об информации «под капотом»:

    • Что такое бот с технической точки зрения
    • Из каких компонентов состоит
    • Как эти компоненты работают вместе

  3. Напишите краткое руководство, описывающее шаги, необходимые для создания бота (со ссылкой на раздел «Настройка среды бота» для дальнейшего чтения). Это руководство будет размещено на странице «Конфигурация среды».

Таким образом, разработчик будет иметь четкое представление о природе ботов и о том, на что они способны. С этого момента разработчик сможет создать своего первого бота.

Результаты: Пересмотренные, простые в использовании вводные руководства с информацией об экосистеме и архитектуре ботов.

НЕДЕЛЯ 3–9

Недели с 3 по 9 будут посвящены унификации всех документов по ботам в репозиториях GitHub и переносу этих документов в основную документацию (https://rocket.chat/docs/bots/). Эти действия можно разделить на несколько итераций:

  1. Определение

    Определение списка подпроектов бота, которые необходимо перенести в основную документацию. Определите, как должны работать сайты ботов после переноса (некоторые боты, например bbot (http://bbot.chat)) имеют помимо github отдельные сайты с документацией).

  2. Шаблон

    Определение и создание шаблона (способа) для организации информации внутри подпроектов ботов, определенных на 1-м этапе. Этот шаблон может выглядеть следующим образом:

    а. Клонировать репозиторий

    б. Установить зависимости

    в. Настройка бота

    д. Запустить бота

    е. Расширенная конфигурация

    ф. Дальнейшие шаги

    Команды, которые включают нетривиальные выходные данные (например, «запустить бота»), должны сопровождаться живыми презентациями этих результатов с помощью инструмента «Term Sheets» (https://neatsoftware.github.io/term-sheets/).

    Кроме того, чтобы сделать начальный этап «быстрого старта» (шаги a–d) более понятным, все этапы также будут объединены в одну живую презентацию.

    Чтобы новички чувствовали себя в безопасности от потенциальных сбоев, примеры кода должны быть предоставлены в игровой среде (с использованием Glitch, как часть экосистемы Rocket Chat), где новички могут общаться с ботами, у которых есть «пример кода» под -капот.

  3. Подготовка

    Подготовка основной документации для перевода. Это включает в себя создание правильной структуры папок и страниц, а также настройку оглавления в соответствии с этой структурой.

    Окончательная структура может выглядеть следующим образом:

    • Боты
      • Боты Архитектура
      • Создание пользователей-ботов
      • Настройка среды бота
      • Запуск ботов
        • bBot Бот
        • Хубот Бот
        • Боткит-бот
        • Раса Бот
        • Ботпресс Бот

  4. Миграция

    Поочередный перенос определенных подпроектов ботов в основную документацию. Каждая часть документации по боту будет иметь отдельную страницу с подразделами, такими как текущая версия (например, запуск bBot).

    • Запуск ботов
      • bBot Бот
      • Хубот Бот
      • Боткит-бот
      • Раса Бот
      • Ботпресс Бот

  5. Организация

    Будет несколько мероприятий:

    1. Организация информации из репозитория каждого бота на GitHub в соответствии с шаблоном, определенным на втором этапе.
    2. Перемещение общих компонентов (например, переменных среды), связанных со всеми подпроектами ботов, на один уровень вверх в иерархии основной документации и связывание подпроектов ботов с этими компонентами.
    3. Создание примера бота «hello world» для каждой поддерживаемой платформы. Этот пример будет использоваться в качестве бота для начала работы с Rocket.Chat.

Почему это важно? Все 8 подпроектов, поддерживаемых Rocket.Chat: alexa,hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana,hubot-gitsy имеют разбросанную документацию в виде README для разработчиков. Эти файлы README вообще не имеют структуры, содержат устаревшую информацию о том, как начать работу, или содержат слишком много информации (иногда с тройной избыточностью, как у Hubot (https://github.com/RocketChat/hubot-rocketchat) о том, как запустить bot с использованием Docker), а также таблицу, содержащую переменные среды.

Эти аспекты сбивают с толку разработчика (как новичка) из-за огромного уровня детализации. В результате разработчику не удастся запустить бота с помощью всего лишь нескольких команд терминала.

После завершения переноса и оптимизации в существующих репозиториях ботов на github появятся файлы README, ссылающиеся на основную документацию.

Это обеспечит следующие преимущества: - Единая структура, которая облегчит разработчикам работу с новыми ботами. - Единый источник достоверной информации о документации по ботам. - Легче найти необходимую информацию о любом боте благодаря унифицированной структуре.

Результаты: организованы в одном месте (основная документация) с простыми для понимания инструкциями по созданию, настройке и запуску ботов, поддерживаемых Rocket.Chat.

НЕДЕЛЯ 10

Эта неделя будет посвящена настройке JSDoc (https://devdocs.io/jsdoc/) для максимизации ценности встроенных комментариев. Это включает в себя:

  1. Обеспечение правильной настройки JSDoc для анализа комментариев к методам драйвера (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods).
  2. Установите postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme), чтобы сделать результирующий вывод HTML более понятным и удобным для разработчиков.
  3. Определение места, где будут публиковаться артефакты документации JSDoc.
  4. Описание всех функций (в файле dist/lib/driver.js), связанных с методами драйвера. Это включает в себя:
    • Добавление/редактирование описаний методов
    • Добавление/редактирование описаний параметров метода
    • Добавление/редактирование примеров запросов методов, если применимо.
    • Добавление/редактирование примеров ответов метода, если применимо

Встроенную документацию легче писать и поддерживать с точки зрения разработчика, а ее механизм автоматического создания позволяет избавиться от статической документации, размещенной на GitHub ( https://github.com/RocketChat/Rocket.Chat.js.SDK#driver- методы ), которые необходимо обновлять отдельно при каждом изменении методов SDK.

НЕДЕЛЯ 11

Эта неделя будет полностью посвящена завершению описания методов драйвера. После завершения описания будут проверены на точность и последовательность, а затем новая документация будет опубликована во всем мире.

НЕДЕЛЯ 12

Завершение выполненной работы. Приемочные проверки.