이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- moja global
- 기술 문서 작성자:
- Tlazypanda
- 프로젝트 이름:
- FLINT용 기술 온보딩 가이드 문서
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
신규 참여자가 최소한의 유지보수자 지원으로 쉽게 시작할 수 있도록 기술 온보딩을 통해 신규 참여자를 안내하는 FLINT용 기술 온보딩 가이드 문서입니다.
프로젝트 문제
다음은 현재 문서와 관련된 가장 중요한 문제의 목록입니다. - 로컬 설정 가이드 안내의 일부가 정리되지 않아 신규 기여자가 시작하기 어렵습니다. - FLINT의 여러 저장소에 목적에 관한 문서가 없고 서로 연결되어 있지 않아 신규 사용자가 설치할 저장소를 파악하기 어렵습니다. - Windows 설치는 문서화되어 있지만 Linux 기반 설치 문서에는 개선의 여지가 있습니다. - Git 워크플로는 현재 문서의 일부가 아닙니다.
제안 솔루션
이 제안서에서는 신규 참여자가 최소한의 지원으로 쉽게 시작할 수 있도록 기술 온보딩을 통해 신규 참여자를 안내하는 솔루션을 제시합니다. 이렇게 하려면 현재 문서를 리팩터링하여 초보자 친화적으로 만들고 사용 가능한 모든 문서를 위한 중앙 독립형 저장소를 유지합니다. 이 프로젝트는 세 단계로 나뉩니다.- - 기존 문서 검토 및 리팩터링: 이 단계의 목표는 현재 가이드를 검토하고 신규 참여자가 간결하고 쉽게 이해할 수 있도록 리팩터링하는 것입니다. 또한 배지, 그림 이모티콘, '초보자만 해당' 또는 '처음 시작하기 좋은 문제' 태그가 지정된 문제에 관한 정보를 추가하여 초보자 친화적으로 문서를 수정해야 합니다. - 중앙 독립형 문서 저장소 만들기: 이 단계의 목표는 독립형 저장소에 논리적 순차 순서로 사용 가능한 모든 문서를 연결하는 것입니다. 여기에는 참여 가이드라인, 프로젝트 설정 안내, 단계별 가이드의 순서 지정이 포함됩니다. - 신규 개발자를 위한 개발자 워크플로 및 커뮤니티 웹사이트 추가: 이 단계의 목표는 테스트 및 QA 가이드라인과 함께 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 파이프라인 도구, 노출 범위 봇 및 자동 품질 검사가 코드를 대상으로 실행되는 새로운 CI/CD 파이프라인 도구를 도입합니다. 또한 테스트가 실패할 경우 누구에게 문의해야 하는지에 관한 가이드라인을 제공합니다.
- 워크플로를 용이하게 하는 데 사용되는 봇(예: Zulipbot: 봇이 표시될 콘텐츠 템플릿을 디자인하고 사용자가 봇을 이해하고 참여하여 봇 구성을 개선할 수 있는 문서를 제공합니다.)
- 풀 리퀘스트 수동 테스트 및 제출: 특정 표준에 따라 풀 리퀘스트를 수동으로 테스트하고 풀 리퀘스트 제출 시 스크린샷/GIF 형식으로 결과를 업로드하는 방법에 관한 문서를 제공합니다.
- 참여자가 따라야 하는 풀 리퀘스트 검토 가이드라인: 검토를 위해 특정 팀을 태그하고 유지보육자가 응답할 수 있도록 '검토 필요'와 같은 라벨을 풀 리퀘스트에 추가하는 방법에 관한 가이드라인입니다.
커뮤니티 웹사이트:
커뮤니티 웹사이트에는 다음과 같은 기능이 있습니다.
- 워크플로에 관한 정보: 워크플로는 신규 참여자가 시작할 수 있는 일련의 작업으로 구성됩니다.예를 들어 신규 참여자가 처음 사용자 문제를 소유한 후 다른 사용자를 위해 처음 사용자 문제를 만들고 의견을 제공하고 풀 리퀘스트를 검토하여 다른 사용자를 돕습니다.
- 신규 사용자 전용 문제 목록: 신규 사용자 또는 신규 참여자를 위해 특별히 마련된 문제 목록입니다.
- 오래된 문제 목록: 오랫동안 처리되지 않아 참여자가 선택할 수 있는 문제 목록입니다.
- 참여자 목록: 지금까지 Moja Global 저장소에 기여한 참여자의 목록입니다.
- 최근 참여자: 최근 Moja Global 저장소에 참여한 참여자 목록입니다.
- 채팅 포럼 가입 링크: 문의사항을 해결하고 프로젝트에 대해 추가로 논의할 수 있는 Slack 커뮤니티에 가입할 수 있는 정보 및 링크입니다.