Season of Docs는 Google 오픈소스 프로그램 사무실에서 관리하는 지속가능성 프로그램입니다. Season of Docs의 목표는 다음과 같습니다.
- 오픈소스 프로젝트가 문서로 프로젝트 문제를 해결할 수 있도록 지원 제공
- 기술 문서 작성자에게 오픈소스 경험을 쌓을 기회 제공
- 오픈소스, 문서, 기술 문서 작성에 대한 인식 제고
- 오픈소스 문서의 효과적인 측정항목에 관한 정보 수집 및 공유
Season of Docs에 관한 자세한 내용은 프로그램 웹사이트에서 확인할 수 있습니다.
2022 프로그램 개요
Season of Docs의 작동 방식
Season of Docs에서 조직은 프로젝트 제안서를 제출하여 신청합니다. 프로젝트 제안서에는 다음이 포함됩니다.
- 조직에 관한 정보
- 프로젝트가 직면한 문제에 관한 설명
- 프로젝트에서 문서를 사용하여 문제를 해결하는 방법
- 프로젝트에서 문서의 효과를 측정하는 방법 (측정항목)
- 작업 일정
- 프로젝트 예산
- 조직의 유사한 프로그램 경험 또는 Season of Docs 관리자가 프로젝트와 문제를 이해하는 데 도움이 되는 기타 정보와 같은 추가 정보
프로그램에 참여가 수락되면 조직은 자체 기술 문서 작성자를 직접 채용합니다. Season of Docs는 Open Collective를 사용하여 조직에 자금을 지원하고 조직은 Open Collective를 통해 기술 문서 작성자에게 비용을 지불합니다. 프로젝트 예산 및 결제는 투명합니다. 예산은 Season of Docs 사이트에서 제공되는 조직 프로젝트 제안서에 포함되어 있으며 결제는 Season of Docs Open Collective 계정에서 확인할 수 있습니다.
조직은 사례 연구 보고서를 제출할 때 프로그램을 성공적으로 완료한 것으로 간주됩니다. 조직은 또한 프로그램 기간 동안 월별 평가를 완료하고 프로그램 완료 후 1년 동안 분기별 후속 설문조사 3개를 작성해야 합니다.
2022 주요사항
“새 문서가 출시된 후 Casbin 및 Casdoor의 일일 방문자 수가 거의 두 배로 늘었고 이탈률이 약 30% 감소했습니다.” —Casbin
“이 프로젝트의 즐거운 결과는 [기술 문서 작성자] 가 커뮤니티에서 리더십 역할을 맡게 된 것입니다. 두 기여자 모두 이제 실무 그룹 및 커뮤니티 회의를 주도하고 프로젝트의 설계 및 유지보수에 기여하고 있습니다.” —moja-global
“[GSoD] 를 통해 일반적인 설정에서는 매우 어려운 두 명의 재능 있는 기술 문서 작성자를 채용할 수 있었습니다. 이들은 OpenMined에 계속해서 활발하게 OS 기여자로 활동하고 있으며 함께 훌륭한 업무 경험을 쌓았습니다.” —OpenMined
“또한 새로운 매뉴얼은 계산 질량 분석법을 처음 접하는 사람들에게 훨씬 더 쉽습니다. 이 점을 설명하기 위해 CZI 지원금은 역사적으로 소외된 개인에게도 수당을 제공하며 일부 수상자는 새로운 OpenMS 매뉴얼을 사용하여 6주간의 인턴십 기간을 시작하고 새로운 매뉴얼에 대해 긍정적인 리뷰를 제공했습니다.” —OpenMS
2022 요약 데이터
2022년 Season of Docs 프로그램은 67건의 신청서 중에서 31개 프로젝트를 수락했으며 30개 프로젝트가 프로그램을 성공적으로 완료했습니다. 수락된 31개 조직 중 17개 조직이 재신청자였습니다.
수락된 31개 프로젝트에서 58명의 기술 문서 작성자를 채용했습니다. 190명이 넘는 기술 문서 작성자가 Season of Docs GitHub 저장소에 연락처 정보와 포트폴리오 링크를 추가하여 프로그램 참여에 관심을 표명했습니다.
2022 프로그램의 경우:
- 100% 의 조직이 신청 절차에 대해 긍정적인 경험을 했습니다.
- 100% 의 조직이 프로그램 웹사이트 문서/콘텐츠에 대해 긍정적인 경험을 했습니다.
- 93% 의 조직이 프로그램에 대해 긍정적인 경험을 했습니다.
- 90% 의 조직이 문서 프로젝트가 성공적이라고 생각했습니다.
조직 정보
Season of Docs 2022에 참여한 조직은 다양한 오픈소스 프로젝트를 대표했습니다. 2022년 코호트에는 다음이 포함되었습니다.
- AsyncAPI, SpyderIDE와 같은 개발 도구
- Julia, LFortran, R, p5.js와 같은 프로그래밍 언어 및 프레임워크
- CERN-HSF, SymPy와 같은 과학 프로젝트
- Mautic, Open Food Facts, Talawa, Ushahidi와 같은 최종 사용자 애플리케이션
- ExpressLRS, Open-RMF와 같은 하드웨어 및 로봇 공학 프로젝트
- GeomScale, GeomStats, OpenMined, Weaviate와 같은 데이터 프로젝트
- cert-manager, NimbleEdge, Cilium과 같은 클라우드 및 인프라 프로젝트
Google은 프로젝트에 관한 메타데이터 (예: 설립일, 기여자의 지리적 분포, 기여자 수, 사용자층 규모)를 수집하지 않았습니다.
Google은 프로젝트에 사용된 오픈소스 라이선스를 표시하도록 요청했습니다.
문서 프로젝트 정보
문서 문제
2022 프로그램에서 조직이 문서로 해결하고자 했던 주요 문제는 다음과 같습니다.
조직은 여러 문서 문제를 보고할 수 있습니다. 자세한 내용은 각 조직의 원본 프로젝트 제안서와 전체 사례 연구에 연결되는 Season of Docs 2022 결과 페이지를 참고하세요.
생성된 문서 유형
2022 사례 연구에서 가장 일반적으로 언급된 문서 유형은 방법 문서였습니다.
사례 연구에서 언급된 기타 문서 유형은 다음과 같습니다.
- 빠른 시작
- 용어집
- FAQ
- Knowledgebase
- 구성요소
- 블로그/소셜 미디어 콘텐츠
- 유지관리자 가이드
이러한 카테고리 중 일부는 모호하며 단일 문서 프로젝트에 여러 문서 유형 또는 기능이 포함될 수 있습니다.
자세한 내용은 각 조직의 원본 프로젝트 제안서와 전체 사례 연구에 연결되는 Season of Docs 2022 결과 페이지를 참고하세요.
예산
평균 예산 요청은 11,679달러였고 중간값은 12,150달러였습니다. 5개 조직이 가장 높은 지원금 (15,000달러)을 요청하고 받았으며 3개 조직이 가장 낮은 지원금 (5,000~7,000달러)을 요청했습니다.
측정항목
프로젝트는 사례 연구에서 문서 프로젝트의 성공 여부를 측정하는 데 사용한 측정항목을 설명했습니다.
제안된 주요 측정항목은 다음과 같습니다.
제안된 기타 측정항목은 다음과 같습니다.
- 더 많은 문서 가져오기 요청/기여
- 문서 페이지에 관한 직접적인 의견
- 페이지에서 보낸 시간
- 제기된 문제 (사용의 프록시)
- 포럼 참여자
- 파트너/자원봉사자/통합 수
- 이탈률 감소
- 커뮤니티의 인식도 증가
기술 문서 작성 프로젝트를 완료하고 사례 연구를 제출하는 데 걸리는 시간이 짧기 때문에 2022 코호트의 대부분은 사례 연구를 제출할 때 초기 측정항목이 충족되었는지 여부를 판단할 수 있을 만큼 충분한 데이터를 수집하지 못했습니다.
2023년에 후속 설문조사 답변을 받으면 이 보고서를 업데이트하여 측정항목을 달성했거나 측정항목을 수정한 프로젝트에 관한 정보를 추가할 예정입니다.
자세한 내용은 각 조직의 원본 프로젝트 제안서와 전체 사례 연구에 연결되는 Season of Docs 2022 결과 페이지를 참고하세요.
기술 문서 작성자와의 협력
Season of Docs 프로그램에서 프로젝트는 기술 문서 작성자를 직접 채용하고 인터뷰하고 채용하고 비용을 지불해야 합니다. 기술 문서 작성자는 GitHub 저장소의 Season of Docs에서 유지관리하는 디렉터리에 자신을 추가할 수 있지만 Season of Docs 직원은 기술 문서 작성자를 검증하거나 추천하지 않습니다.
오픈소스 프로젝트를 위한 기술 문서 작성자 채용 권장사항
프로젝트는 기술 문서 작성자를 채용하고 채용하고 협력하는 데 관한 권장사항을 공유하도록 요청받았습니다. 주요 권장사항은 다음과 같습니다.
채용
- 이력서 검토만 하는 대신 더 적은 수의 지원자를 인터뷰하고 실시간 실습 세션을 사용합니다.
- 프로젝트의 언어 또는 도구에 관한 숙련도보다 서면 및 구두 커뮤니케이션 기술을 중요하게 생각합니다.
- 기술 문서 작성자가 프로젝트를 진행하는 데 필요한 도메인 지식을 어떻게 습득할 것인지에 관해 직접 질문합니다.
- 프로젝트의 사명에 열정을 갖고 핵심 오픈소스 가치를 공유하는 사람이 프로젝트 전체에서 동기를 유지할 가능성이 더 큽니다.
- 다양한 관점과 배경이 프로젝트에 도움이 되므로 전 세계의 지원자에게 열린 마음을 가지세요. 하지만 너무 많은 상충되는 시간대에 문서 작성자와 멘토가 있으면 원활한 커뮤니케이션을 유지하는 데 많은 노력이 필요할 수 있습니다.
채용
- 결과물, 결제 일정, 구체적인 시간 약정을 명확하게 명시하는 계약을 사용합니다.
- 프로젝트에 알려지지 않은 부분이 많은 경우 문서 작성과 별도로 검색 또는 연구를 위한 주요 일정을 포함합니다.
조정 및 커뮤니케이션
- 프로젝트에 참여하는 모든 사람이 컨텍스트와 다음 단계를 더 쉽게 이해할 수 있도록 결정을 기록하는 회의 로그를 유지합니다.
- 주간 통화, 일일 이메일, 채팅 채널의 상태 업데이트 등 예상되는 커뮤니케이션과 빈도를 명확하게 설명합니다.
- 대응력이 뛰어나고 '무엇'뿐만 아니라 '이유'를 포함하는 명확한 의견을 제공합니다.
- 기술 문서 작성자를 더 넓은 커뮤니티와 연결하여 컨텍스트를 제공하고 작업을 공유합니다.
프로세스 및 도구
- Season of Docs 프로그램 이후에도 지속되고 전체 커뮤니티가 기여할 수 있는 문서 프로세스를 만듭니다.
- 문서 검토는 코드 검토만큼 시간이 오래 걸리고 집중적입니다. 충분한 시간을 할애하세요.
명확성을 위해 일부 권장사항이 수정되고 요약되었습니다.
2021 프로그램과 마찬가지로 Season of Docs 2022의 대부분의 기술 문서 작성자는 함께 작업한 조직에 직접 신청했습니다.
기술 문서 작성자와의 협력 시 일반적인 문제
2022 프로그램에서 기술 문서 작성자와의 협력에 문제를 보고한 프로젝트가 더 적었습니다. 기술 문서 작성자가 질병, 정규직 채용, 시간 약정 불이행으로 인해 프로그램을 완료하지 못하는 것이 가장 큰 문제였습니다.
한 프로젝트에서는 문서 프로젝트가 Google Summer of Code의 일부로 진행되는 작업에 의존하며 이러한 종속성을 관리하기 어렵다고 보고했습니다. 다른 프로젝트에서는 기술 문서 작성자가 문서화해야 하는 하드웨어가 작성자의 국가에서 국방부에 의해 압수되어 가져올 수 없게 되면서 어려움을 겪었습니다.
후속 설문조사
2023년 5월, 8월, 11월에 2022년 참가자에게 후속 설문조사 3개가 전송됩니다. 결과가 수신되면 이 섹션을 업데이트할 예정입니다.
향후 질문
항상 그렇듯이 오픈소스의 문서에 관해 더 많이 알게 될수록 더 많이 알고 싶어집니다.
향후 시즌에는 다음을 기대합니다.
- 프로젝트 연령, 커뮤니티 규모 또는 언어와 문서 요구사항 간의 상관관계를 찾기 위해 더 많은 프로젝트 메타데이터 수집
- 문서 프로젝트를 분석하여 공유 가능한 템플릿으로 일반화할 수 있는지 확인
- 오픈소스 프로젝트에서 기술 문서 작성자를 인터뷰하기 위한 평가 기준 개발
조사하고 싶은 질문이 많지만 Season of Docs에 참여하는 오픈소스 프로젝트 관리자와 유지관리자의 시간도 존중하고 싶습니다. 프로그램의 최우선순위는 프로젝트가 문서 문제를 해결하도록 지원하는 것입니다.