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