Rocket.Chat 프로젝트

이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
Rocket.Chat
테크니컬 라이터:
미스터 골드
프로젝트 이름:
봇 문서
프로젝트 기간:
표준 기간 (3개월)

Project description

프로젝트 요약

채팅 봇은 오늘날 최첨단 기술입니다. 채팅 소프트웨어와 봇의 전반적인 성장률과 음성 인식 및 자동화의 증가로 인해 이해하고 사용하기 쉬운 봇 문서를 만들어야 합니다.

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

이 프로젝트의 목표는 지식 격차를 해소하고 경험이 적은 초보 개발자가 최신 기술의 이점을 열성적인 잠재고객에게 제공할 수 있도록 장려하는 것입니다. 이를 위해서는 봇 빌더에게 Rocket.Chat에서 자체 봇을 개발할 수 있는 간소화된 경험을 제공해야 합니다. 이 목표는 Rocket.Chat을 궁극적인 BOT 배포 목표에 관계없이 개발자들이 챗봇 아이디어를 혁신하고, 만들고, 테스트할 수 있는 선호 오픈소스 플랫폼으로 만드는 것을 목표로 합니다.

프로젝트 문제

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

  1. 직관적이지 않고 친근하지 않은 봇에 관한 일반적인 정보
  2. 봇 아키텍처와 관련된 분산된 중복 섹션
  3. 단일 정보 소스가 없는 정리되지 않은 '시작' 가이드 안내
  4. 안내가 부족하거나 상세한 설명이 부족함
  5. 암시적 및 모호한 봇 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)
    • 봇 사용자 만들기 (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 봇
        • 라사 봇
        • Botpress 봇

  4. 마이그레이션

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

    • 봇 실행
      • bBot 봇
      • 허봇 봇
      • Botkit 봇
      • 라사 봇
      • Botpress 봇

  5. 조직

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

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

이 정책이 왜 중요할까요? R 일부 이러한 리드미에는 구조가 없거나 시작 방법에 관한 오래된 정보가 포함되어 있거나 (때때로 Docker를 사용하여 봇을 실행하는 방법에 관한 Hubot (https://github.com/RocketChat/hubot-rocketchat) 삼중 중복화와 같은 정보), 환경 변수가 포함된 표가 너무 많습니다.

이러한 측면은 초보자인 개발자에게 엄청난 수준의 세부정보를 혼란스럽게 합니다. 그 결과 개발자가 몇 가지 터미널 명령어만으로 봇을 가동하고 실행하는 데 실패하게 됩니다.

전송과 최적화가 완료되면 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)에 대한 설명 여기에는 다음이 포함됩니다.
    • 메서드 설명 추가/편집
    • 메서드 매개변수의 설명 추가/수정
    • 메서드 요청의 추가/수정 예시(해당하는 경우)
    • 메서드 응답의 추가/수정 예시(해당하는 경우)

인라인 문서는 개발자의 관점에서 더 쉽게 작성하고 유지관리할 수 있으며 자동 생성 메커니즘을 통해 SDK 메서드의 각 변경사항에 따라 별도로 업데이트되어야 하는 GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)에 호스팅된 정적 문서를 제거할 수 있습니다.

11주 차

이번 주에는 드라이버 메서드 설명을 마무리하는 시간을 갖겠습니다. 작성이 완료되면 설명의 정확성과 일관성이 테스트되며 새 문서가 전 세계에 게시됩니다.

12주 차

완료된 작업 마무리 승인 확인