이 페이지에는 Google 시즌의 Docs에 승인된 기술 글쓰기 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- GenPipes
- 기술 문서 작성자:
- shaloo
- 프로젝트 이름:
- 'Read The Docs'에서 GenPipes 문서 설정
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
'Read The Docs'에서 GenPipes 문서를 설정하는 목표를 달성하기 위한 3단계 계획을 제안합니다.
1단계: PoC
신규 사용자 / 연구원으로서 GenPipes의 기존 문서 검토
- 누락된 정보, 부정확성 식별
- 새 문서 주제 제안 (필요한 경우)
- 신규 사용자를 중심으로 타겟층을 공략하기 위한 정보 아키텍처 맵 초안
(참고: 이 단계에서는 RTD용 genpipes 문서를 호스팅할 수 있는 새로운 GitHub 저장소 설정과 관련된 GenPipes 멘토의 입력이 필요할 수도 있습니다. 이 GitHub 저장소는 RTD 빌드 파이프라인의 모든 문서를 가져오는 데 사용할 수 있습니다. 준수해야 하는 경우 GenPipes 저장소 규칙 및 문서 소스 관리 가이드라인에 대한 정보가 필요할 수 있습니다. 그렇지 않으면 표준을 사용할 수 있습니다. 또한 PoC의 경우, GitHub 계정(예: https://gpdocs.readthedocs.io/en/latest/)을 사용하여 이 제안서를 위해 만든 샘플 RTD 저장소 설정을 시연할 수 있습니다.)
이전 단계의 검토 및 분석을 기반으로 제안된 GenPipes 문서 구조 / 색인의 기본 골격을 만들어 RTD 사이트에 게시
- 여기에는 GitHub 저장소 생성 (예: Sphinx 도구 사용) 및 기본 문서 파일이 포함됩니다.
- 또한 다양한 정보 섹션 / 흐름을 고려하여 신규 사용자와 숙련된 사용자 모두를 고려한 새로운 목차를 작성합니다.
기본 골격 TOC 검토 / 승인 받기
GenPipes GSoD 평가 단계에서 RTD에 호스팅된 이 샘플을 통해 GenPipes의 가치를 창출하려고 했습니다. 이 링크는 데모 전용이며 보호된 링크이며 아직 RTD에 공개적으로 표시되지 않습니다. 후보에 선정되는지와 관계없이 이 데모를 사용하여 GenPipes RTD 작업을 시작할 수 있습니다. c3g/GenPipes GitHub 저장소에 소스를 이미 체크인했습니다. 이전에 Skype '화면 공유' 토론 중에 멘토인 롤라와 헥터가 이 앱을 좋아했기 때문에 GSoD Gods도 이 앱을 보고 싶어할 수도 있다고 생각했습니다. 현재는 대략적인 틀만 있지만 7월 30일까지 시간이 허락하는 대로 업데이트할 계획입니다.
https://genpipes.readthedocs.io/en/latest/
2단계: GenPipes 문서 v0.9 문서 세트 만들기
GSoD 타임라인을 염두에 두고 RTD에서 호스팅하기 위해 Sphinx/첫 번째 문서로 가져오거나 연결하거나 변환할 수 있는 현재 또는 기존 GenPipes 문서를 파악합니다.
확인된 문서를 rst 형식으로 변환하고 필요한 경우 해당하는 경우 새 문서를 만들고 가능한 한 관련성 있는 문서는 재사용합니다.
- 이 초기 문서 세트를 ReadTheDocs로 가져와 개념 증명으로 보호된 저장소로 호스팅합니다. 검토/공식 전환이 승인될 때까지 신규 사용자는 GenPipes 원본 문서를 참고하라는 메모를 미리 남깁니다.
검토/과정 수정/업데이트
3단계: RTD에서 초안 수정, 검토, 게시
제안된 GenPipes 새 문서 구조에 대한 세부정보를 GenPipes TOC에 작성하십시오. – 처음 몇 개 문서 외에 추가 문서 (GenPipes Readme), 개념, 튜토리얼 등 추가 문서를 추가합니다.
TOC에 신규 사용자, 숙련된 GenPipes 사용자, GenPipes 개발자 등을 고려한 명확한 구분을 추가합니다.
RTD (Sphinx 빌드)를 통한 부분 자동화를 통해 GenPipes 문서 세트를 사용자가 어떻게 관리하고 수정할 수 있는지, C3G에서 외부 문서 참여자의 경우 이를 허용하는지 작업 프로세스를 제안하고 논의합니다. 이 경우 코딩 가이드라인과 유사한 문서 업데이트 가이드라인을 만들어야 할 수 있습니다. 하위 단계가 더 필요할 수 있습니다. 예를 들어 GenPipes 문서에서 PR 승인 전에 맞춤법 검사를 자동화합니다.
신고
마지막으로 경험, 로그, 멘토의 의견을 바탕으로 GSoD 보고서를 만듭니다.
기타 의견
향후 (3개월 이후) 해당하는 경우 GenPipes를 장기적으로 유지하는 데 도움을 드릴 수 있습니다. 또는 필요한 경우 다른 사람에게 똑같이 교육할 수도 있습니다. 처음 3개월의 결과를 토대로 이를 파악할 수 있습니다.
또한 간편한 온보딩에 도움이 되는 GenPipes 3페이지 브리핑을 만드는 프로젝트 제안 아이디어를 추가로 제안합니다. 지금은 신규 사용자가 GenPipes 사용을 시작하기 전에 여러 번 거쳐야 합니다. 문서는 좋지만 내용이 흩어져 있으며 신규 사용자에게 도움이 되지 않기 때문입니다. 3개월 이내에 완료할 수 있을지는 모르겠지만 한번 시도해 보겠습니다.
이 제안서와 제안서가 어떻게 작성되었는지 (기록)는 https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing에서도 확인할 수 있습니다.