이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- moja Global
- 테크니컬 라이터:
- 트라지판다
- 프로젝트 이름:
- FLINT용 테크니컬 온보딩 가이드 문서
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
신규 참여자가 유지관리 담당자의 최소한의 지원으로 쉽게 시작할 수 있도록 기술 온보딩을 통해 신규 기여자를 안내하는 FLINT용 기술 온보딩 가이드 문서입니다.
프로젝트 문제
다음은 현재 문서와 관련된 가장 중요한 문제 목록입니다. - 로컬 설정 가이드 안내가 정리되어 있지 않아 새 기여자가 시작하는 데 어려움이 있습니다. - FLINT의 여러 저장소가 용도에 관한 문서가 없고 서로 연결되어 있지 않으므로 신규 사용자가 설치할 저장소를 식별하기가 어렵습니다. - Windows 설치는 잘 문서화되어 있지만 Linux 기반 설치 문서는 개선의 여지가 있습니다. - Git 워크플로는 현재 문서에 포함되어 있지 않습니다.
제안 솔루션
이 제안서는 새 기여자가 유지관리 담당자로부터 최소한의 지원으로 쉽게 시작할 수 있도록 기술 온보딩을 통해 새 기여자를 안내하는 솔루션을 제공합니다. 이를 위해서는 현재 문서를 초보자 친화적으로 리팩터링하고 모든 문서를 보관하는 중앙 독립형 저장소를 유지하는 것이 좋습니다. 프로젝트는 세 단계로 나뉩니다. - 기존 문서 검토 및 리팩터링: 이 단계의 목표는 현재 가이드를 검토하고, 새 가이드를 통해 간결하고 쉽게 이해할 수 있도록 리팩터링하는 것입니다. 또한 초보자를 쉽게 이해할 수 있도록 배지, 그림 이모티콘, '최초 문제' 또는 '좋은 첫 문제' 태그로 라벨이 지정된 문제에 관한 정보를 추가하여 문서를 수정해야 합니다. - 중앙 독립형 문서 저장소 만들기: 이 단계의 목표는 사용 가능한 모든 문서를 독립형 저장소에서 논리적 순차적 순서로 연결하는 것입니다. 여기에는 후원 가이드라인, 프로젝트 설정 안내, 단계별 안내를 주문하는 작업이 포함됩니다. - 새 개발자를 위한 개발자 워크플로 및 커뮤니티 웹사이트 추가: 이 단계의 목표는 테스트 및 품질보증 가이드라인과 함께 git 참여 가이드라인과 프로젝트의 기술 아키텍처가 포함된 개발자 워크플로를 추가하는 것입니다. 제안된 커뮤니티 웹사이트는 워크플로, 새 기여자가 신청할 수 있는 최초 문제, 모든 참여자 목록을 표시하는 단일 페이지 애플리케이션입니다. 1단계: 기존 문서 검토 및 리팩터링:
다음 저장소의 현재 문서를 수정하세요. - FLINT: 현재 문서는 그다지 자세하지 않으며 필요한 선행 조건 라이브러리의 순차적 순서를 제공하지 않습니다. 단계별 안내 가이드는 여러 개의 PDF로 나뉘어 있지만 더 간결한 방식으로 한 곳에 통합할 수 있습니다. 또한 설치 가이드는 Windows에 맞춰 마련되지만 Linux 설치의 경우 FLINT.docker 저장소로 리디렉션하는 것이 유용할 수 있습니다. - FLINT.docker: 현재 문서에서는 Docker를 통해 FLINT의 Linux 설치를 제공하기 위해 이 저장소를 설정하는 목적을 제공하지 않습니다. docker를 통한 지원은 Ubuntu 18.04 (Bionic Beaver)로만 제한되지만, 다른 Linux 기반 배포판으로도 확장할 수 있습니다. 또한 최신 문서에서는 dockerfile을 설정하는 순차적 방식에 중점을 두고 makefile에서 빌드하는 방법에 관한 충분한 정보도 제공해야 합니다. - FLINT.example: 현재 문서에서는 FLINT 사용 방법의 예를 제공하기 위해 이 저장소를 설정하는 목적을 제공하지 않습니다. 서로 다른 샘플 실행을 특정 실행 명령에 따라 더 잘 구분할 수 있습니다. 또한 이 저장소를 기본 FLINT 저장소에 연결해야 실제 예시를 확인하기 위해 여기에서 탐색할 수 있는 방법을 사용자에게 제공할 수 있습니다.
현재 문서에 다음 정보를 추가해야 합니다. - Git 및 GitHub 사용: 저장소의 원격 업스트림을 포크하고 클론한 다음 설정하는 방법에 관한 단계별 안내가 포함되어 있습니다. 또한 최신 마스터를 기준으로 리베이스하고 병합 충돌을 처리하는 방법에 관한 정보도 제공합니다. - 배지 및 그림 이모티콘: 현재 문서에는 신규 참여자가 환영받는 느낌을 받고 덜 부담스러울 수 있는 문제를 발견하는 데 도움이 되는 배지와 그림 이모티콘이 없습니다. - 초보자용/초보자용 문제에 관한 정보: 신규 참여자를 초보자 친화적인 문제 및 커뮤니티 웹사이트로 리디렉션하는 데 도움이 됩니다. - Import-me 저장소에 대한 정보: Import-me 저장소는 Moja Global 저장소를 점프 시작하기 위한 기준 템플릿 역할을 합니다. 현재 문서에서는 이와 동일한 내용의 중요도가 언급되어 있지 않습니다. Import-me 저장소를 언급하도록 업데이트해야 하며 새 저장소 생성 시 이 저장소를 템플릿으로 선택하는 단계도 추가해야 합니다. 또한 코더가 Import-me 저장소의 추가 기능을 제안할 수 있는 프로세스도 마련해야 합니다.
2단계: 중앙 독립형 문서 저장소 만들기
호스팅 플랫폼에 사용할 도구:
이 호스팅 플랫폼에 제안된 도구는 다음과 같은 이유로 Read The Docs를 사용합니다.- - 다양한 호스팅 플랫폼 중에서 높은 순위로 선정됩니다. - 커밋 푸시 시 자동 업데이트 - 대규모 커뮤니티에서 사용하기 때문에 쉽게 설정하고 문제 해결 지원을 이용할 수 있습니다. - 문서는 reStructuredText를 사용하여 형식이 지정되고 출력은 Sphinx로 컴파일됩니다.
모든 콘텐츠를 논리적 순차적인 방식으로 구성합니다.
제안된 콘텐츠 순서는 다음과 같습니다. - 개발자 문서 소개: 이 섹션에서는 Moja Global 및 FLINT를 소개합니다. - 참여: 이 섹션은 '참여 방법'(코드/버그 신고/번역/문서/이벤트 구성 등) 및 '윤리 강령' 하위 섹션으로 구성됩니다. - 개발 설정: 이 섹션은 'Git & GitHub 워크플로', 'Windows 설치', 'Linux 설치'의 하위 섹션으로 구성됩니다. - 개발자 워크플로: 이 섹션에서는 도구 통합 테스트 및 추가 테스트를 위해 통합 테스트를 수행하는 방법에 관한 설명과 추가 테스트 실행 방법에 관한 설명으로 구성됩니다. - 참여: 이 섹션에서는 Moja Global과 연결하고 작업할 수 있도록 Slack 채널과 같은 다양한 소셜 포럼을 제공합니다.
3단계: 새로운 참여자를 위한 개발자 워크플로 및 커뮤니티 웹사이트 추가
개발자 워크플로 문서:
개발자 워크플로 문서는 다음과 같은 하위 섹션으로 구성됩니다.
- 사용된 기술 스택/아키텍처 및 코드에 포함된 다양한 모듈: 구현된 기술 스택, 코드베이스의 다양한 라이브러리 및 모듈에 관해 새 참여자를 알려주는 문서입니다.
- 통합 테스트 및 적용 범위 도구: 테스트에 사용되는 CI/CD 파이프라인 도구, 적용 범위 봇, 코드에 대해 실행되는 자동 품질 검사에 새로운 기여자를 소개합니다. 또한 테스트에 실패할 경우 누구에게 접근해야 하는지에 대한 가이드라인을 제공합니다.
- 워크플로를 간소화하는 데 사용되는 봇(예: Zulipbot: 봇을 표시할 콘텐츠 템플릿 설계, 사용자가 봇을 이해할 수 있도록 문서화, 참여로 봇 구성 개선 등)
- pull 요청 수동 테스트 및 제출: 특정 표준에 따라 pull 요청을 수동으로 테스트하고 pull 요청 제출 시 스크린샷/gif로 결과를 업로드하는 방법에 관한 문서가 제공됩니다.
- 참여자가 후속 조치를 취할 수 있는 pull 요청 검토 가이드라인: 검토를 위해 특정 팀을 태그하고, 유지관리 담당자가 응답할 수 있도록 pull 요청에 '검토 필요'와 같은 라벨을 추가하는 방법에 관한 가이드라인
커뮤니티 웹사이트:
커뮤니티 웹사이트에서 제공하는 기능은 다음과 같습니다.
- 워크플로에 관한 정보: 이 워크플로는 새로운 기여자가 시작할 수 있는 일련의 작업으로 구성됩니다.첫 번째 타이머 문제의 소유권을 주장한 후 다른 사람을 위해 첫 번째 타이머 문제를 만들고, 의견을 제공하고 pull 요청을 검토하여 다른 사용자를 도와주세요.
- 처음 발생한 문제 목록: 신규 사용자 또는 신규 참여자를 대상으로 한 문제 목록입니다.
- 오래된 문제 목록: 장기간 처리되지 않아 참여자가 선정할 수 있는 문제의 목록입니다.
- 참여자 목록: 지금까지 Moja Global 저장소에 참여한 참여자 목록입니다.
- 최근 참여자: 최근에 Moja Global 저장소에 참여한 참여자 목록입니다.
- 채팅 포럼 가입 링크: 쿼리를 해결하고 프로젝트에 관한 추가 토론을 진행하기 위해 Slack 커뮤니티에 가입할 수 있는 정보와 링크입니다.