Rocket.Chat 프로젝트

이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
Rocket.Chat
기술 문서 작성자:
Mister Gold
프로젝트 이름:
봇 문서
프로젝트 길이:
표준 기간 (3개월)

Project description

프로젝트 요약

채팅 봇은 오늘날의 최신 기술입니다. 음성 인식 및 자동화와 함께 채팅 소프트웨어 및 봇의 전반적인 성장률이 급증함에 따라 이해하기 쉽고 사용하기 쉬운 봇 문서를 만들어야 할 필요성이 대두되고 있습니다.

포괄적이고 명확한 문서가 더욱 중요해지므로 기존 봇 문서에 더 쉽게 액세스하고 탐색할 수 있도록 하고, 지원되는 각 프레임워크에 관한 통합된 단계별 안내와 광범위한 예시를 제공해야 합니다. 또한 중복되거나 이해하기 어려운 정보는 삭제하여 정리해야 합니다.

이 프로젝트의 목표는 지식 격차를 해소하고 경험이 부족한 신규 개발자가 첨단 기술의 이점을 기대하는 사용자에게 제공하도록 장려하는 것입니다. 이를 위해 봇 빌더에게 Rocket.Chat에서 자체 봇을 개발할 때 간소화된 환경을 제공하면 됩니다. 이 목표는 궁극적인 BOT 배포 대상과 관계없이 개발자가 챗봇 아이디어를 혁신, 생성, 테스트할 때 선호하는 오픈소스 플랫폼으로 Rocket.Chat을 만드는 것입니다.

프로젝트 문제

다음은 봇 문서와 관련된 가장 중요한 문제 목록입니다.

  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주 차: 결과 평가

주요 성과에 대한 세부 분석

신청서 검토 기간

기간의 첫 번째 부분은 커뮤니티 채널과 소스 코드를 확인하고 프로젝트 전담자에게 연락하는 데 사용됩니다.

두 번째 기간에는 일반적인 참여 문화를 확인하고 참여 가이드 및 권장사항을 검토하는 데 전념할 예정입니다. 이때 처음으로 참여하여 절차가 어떻게 진행되는지 확인할 수 있습니다.

커뮤니티 결속

이번에는 로드맵과 함께 문서 저장소를 자세히 살펴봅니다. 이 정보를 바탕으로 개선할 수 있는 약점 (예: 불완전하거나 누락된 부분)을 파악할 수 있습니다. 가능한 경우 pull 요청을 생성하여 공백을 메웁니다.

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)
    • 'Creating Bot Users'(봇 사용자 만들기)에서 봇과 대화하기(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단계에서 정의된 봇 하위 프로젝트 내에서 정보를 구성하는 템플릿 (방법)을 정의하고 만듭니다. 이 템플릿은 다음과 같이 표시될 수 있습니다.

    a. 저장소 클론

    b. 종속 항목 설치

    c. 봇 구성하기

    d. 봇 실행

    e. 고급 구성

    f. 추가 단계

    사소한 출력 (예: '봇 실행')을 포함하는 명령에는 용어 시트 도구 (https://neatsoftware.github.io/term-sheets/)를 사용하여 해당 출력을 실시간으로 프레젠테이션해야 합니다.

    또한 초기 '빠른 시작' 단계 (단계 a~d)를 더 명확히 하기 위해 모든 단계가 하나의 라이브 프레젠테이션에 결합됩니다.

    신규 사용자가 잠재적인 실패로부터 안전하다고 느낄 수 있도록, 신규 사용자가 '예시 코드'가 내장된 봇과 채팅할 수 있는 플레이그라운드 환경 (Rocket Chat 생태계의 일부인 Glitch 사용)에 코드 예시를 제공해야 합니다.

  3. 준비

    이전을 위한 기본 문서를 준비합니다. 여기에는 적절한 폴더 및 페이지 구조를 만들고 해당 구조에 따라 목차를 조정하는 작업이 포함됩니다.

    최종 구조는 다음과 같습니다.

    • 봇
      • 봇 아키텍처
      • 봇 사용자 만들기
      • 봇 환경 구성
      • 실행 봇
        • bBot 봇
        • 후보트 봇
        • Botkit 봇
        • Rasa 봇
        • Botpress 봇

  4. 마이그레이션

    정의된 봇 하위 프로젝트를 기본 문서로 하나씩 이전합니다. 각 봇 문서에는 현재 버전 (예: bBot 실행)과 같은 하위 섹션이 있는 별도의 페이지가 있습니다.

    • 봇 실행
      • bBot 봇
      • 후보트 봇
      • Botkit 봇
      • Rasa 봇
      • Botpress 봇

  5. 조직

    다음과 같은 활동이 있습니다.

    1. 2단계에서 정의된 템플릿에 따라 각 봇 GitHub 저장소의 정보를 정리합니다.
    2. 모든 봇 하위 프로젝트와 관련된 공통 구성요소 (예: 환경 변수)를 기본 문서의 계층 구조에서 한 단계 위로 이동하고 봇 하위 프로젝트를 이러한 구성요소에 연결
    3. 지원되는 각 프레임워크에 대해 'hello world' 봇의 예를 만듭니다. 이 예시는 Rocket.Chat의 '시작하기' 봇으로 사용됩니다.

이것이 중요한 이유는 무엇인가요? Rocket.Chat에서 지원하는 8개의 하위 프로젝트(alexa, Hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswana, hubot-gitsy)는 모두 개발자 README 형식의 문서가 흩어져 있습니다. 이러한 README는 구조가 전혀 없거나, 시작하는 방법에 관한 오래된 정보가 포함되어 있거나, 너무 많은 정보 (Docker를 사용하여 봇을 실행하는 방법에 관한 hubot (https://github.com/RocketChat/hubot-rocketchat)과 같이 세 번 중복된 경우도 있음)와 환경 변수가 포함된 표를 포함하고 있습니다.

이러한 측면은 신규 개발자를 혼란스럽게 하는 엄청난 수준의 세부사항을 제공합니다. 결과적으로 개발자는 단 몇 가지 터미널 명령만으로도 봇을 준비하고 실행하는 데 실패하게 됩니다.

전송 및 최적화가 완료되면 GitHub의 기존 봇 저장소에 기본 문서를 참조하는 리드미 파일이 생성됩니다.

이를 통해 다음과 같은 이점이 제공됩니다. - 개발자가 새 봇을 더 쉽게 시작할 수 있는 통합 구조 - 봇 문서의 단일 정보 소스 - 통합 구조 덕분에 봇에 관한 필요한 정보를 더 쉽게 찾을 수 있음

결과물: 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에 있음) 설명 여기에는 다음이 포함됩니다.
    • 메서드 설명 추가/편집
    • 메서드 매개변수 설명 추가/수정
    • 메서드 요청 예시 추가/수정(해당하는 경우)
    • 메서드 응답의 예시 추가/수정(해당하는 경우)

인라인 문서는 개발자의 관점에서 작성하고 유지 관리하기가 더 쉽고, 자동 생성 메커니즘을 사용하면 SDK 메서드가 변경될 때마다 별도로 업데이트해야 하는 GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)에 호스팅된 정적 문서를 삭제할 수 있습니다.

11주 차

이번 주에는 드라이버 메서드 설명을 완료하는 데 전념할 예정입니다. 완료되면 설명의 정확성과 일관성을 테스트한 후 새 문서를 전 세계에 게시합니다.

12주 차

완료된 작업의 마무리 수락 확인