이 페이지에는 Google Season of Docs에서 수락된 기술 작문 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- moja Global
- 테크니컬 라이터:
- 트래지판다
- 프로젝트 이름:
- FLINT 기술 온보딩 가이드 문서
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
신규 기여자가 유지관리자의 최소한의 지원으로 쉽게 시작할 수 있도록 기술 온보딩을 통해 신규 기여자를 안내하는 FLINT용 기술 온보딩 가이드 문서
프로젝트 문제
다음은 현재 문서와 관련된 가장 중요한 문제의 목록입니다. - 로컬 설정 가이드 안내가 정리되어 있지 않아 새 기여자가 시작하기가 어렵습니다. - FLINT의 여러 저장소는 용도에 대한 문서가 없고 서로 연결되어 있지 않으므로 초보자가 설치할 저장소를 식별하기가 어렵습니다. - Windows 설치에 대한 문서화가 잘 되어 있지만, Linux 기반 설치 문서에는 개선의 여지가 있습니다. - Git 워크플로는 현재 문서에 포함되지 않습니다.
제안 솔루션
이 제안서는 새 기여자가 유지관리자의 최소한의 지원으로 쉽게 시작할 수 있도록 기술 온보딩을 통해 신규 기여자를 안내하는 솔루션을 제공합니다. 이를 위해서는 현재 문서를 리팩터링하여 초보자 친화적으로 만들고, 제공되는 모든 문서를 위한 중앙 독립형 저장소도 유지할 수 있습니다. 프로젝트는 다음과 같은 세 단계로 나뉩니다.- - 기존 문서 검토 및 리팩토링: 이 단계의 목표는 현재 가이드를 검토하고 새로운 기여자가 간결하고 쉽게 이해할 수 있도록 리팩토링하는 것입니다. 또한 초보자에게 쉽게 접근할 수 있도록 배지, 그림 이모티콘, 문제에 대한 정보를 추가하여 문서를 수정해야 합니다. - 중앙 독립형 문서 저장소 만들기: 이 단계의 목표는 사용 가능한 모든 문서를 독립형 저장소에서 논리적 순차적 순서로 연결하는 것입니다. 여기에는 후원 가이드라인, 프로젝트 설정 안내, 단계별 안내가 포함됩니다. - 신규 개발자를 위한 개발자 워크플로 및 커뮤니티 웹사이트 추가: 이 단계의 목표는 git 기여 가이드라인과 프로젝트의 기술 아키텍처가 포함된 개발자 워크플로를 테스트 및 QA 가이드라인과 함께 추가하는 것입니다. 제안된 커뮤니티 웹사이트는 워크플로, 신규 참여자를 신청할 수 있는 최초 문제, 모든 참여자 목록을 표시하는 단일 페이지 애플리케이션입니다. 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 저장소를 명시하도록 업데이트해야 하며, 새 저장소 생성 시 이를 템플릿으로 선택하는 단계도 추가해야 합니다. 또한 Coder가 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 커뮤니티에 가입할 수 있는 정보와 링크입니다.