현재 단계:
우수사례가 게시되었습니다. 타임라인을 참고하세요.
Season of Docs는 Google 오픈소스 프로그램 사무국에서 관리하는 지속가능성 프로그램입니다. Season of Docs의 목표는 다음과 같습니다.
- 문서를 사용하여 프로젝트 문제를 해결하는 오픈소스 프로젝트 지원
- 기술 작가에게 오픈소스 경험을 얻을 기회 제공
- 오픈소스, 문서, 기술 문서에 대한 인식 제고
- 오픈소스 문서에서 효과적인 측정항목에 관한 정보를 수집하고 공유합니다.
Season of Docs에 대한 자세한 내용은 프로그램 웹사이트에서 확인할 수 있습니다.
2022 프로그램 개요
Season of Docs 작동 방식
시즌 오브 닥스에서는 조직이 프로젝트 제안서를 제출하여 신청합니다. 프로젝트 제안서에는 다음이 포함됩니다.
- 조직에 대한 정보
- 프로젝트에서 발생한 문제에 대한 설명
- 프로젝트에서 문서를 사용하여 문제를 해결하는 방법
- 프로젝트에서 문서의 효과를 측정하는 방법 (측정항목)
- 작업 타임라인
- 프로젝트 예산
- 유사한 프로그램에서의 조직의 경험 또는 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] 를 통해 정규 설정에서는 매우 어려운, 재능 있는 기술 작가 2명을 모집할 수 있었습니다. 이들은 OpenMined의 OS에 계속해서 적극적으로 참여하고 있으며, 함께 일하면서 좋은 경험을 했습니다.” —OpenMined
“또한 새로운 매뉴얼은 컴퓨터 질량 분석을 처음 접하는 사용자에게 훨씬 더 쉽습니다. 이를 예로 들면 CZI는 역사적으로 소외된 개인에게도 장학금을 제공하며, 일부 수상자는 새로운 OpenMS 매뉴얼을 사용하여 6주간의 인턴십을 시작했고 새로운 매뉴얼에 대해 긍정적인 평가를 했습니다." —OpenMS
2022 요약 데이터
2022년 Season of Docs 프로그램은 67건의 신청 중 31건의 프로젝트를 수락했으며 30개 프로젝트가 프로그램을 완료했습니다. 승인된 31개 조직 중 17개 조직은 재신청자였습니다.
승인된 31개 프로젝트는 기술 작가 58명을 고용했습니다. 190명 이상의 기술 작가가 문서 시즌 GitHub 저장소에 연락처 정보와 포트폴리오 링크를 추가하여 프로그램 참여에 관심을 보였습니다.
2022년 프로그램의 경우:
- 100% 의 조직이 신청 절차에 만족했습니다.
- 100% 의 조직이 프로그램 웹사이트 문서/콘텐츠에 관해 긍정적인 경험을 했습니다.
- 93% 의 조직이 프로그램에 만족했습니다.
- 90% 의 조직이 문서 프로젝트가 성공적이라고 생각함
조직 정보
2022년 Season of Docs에 참여한 조직은 다양한 오픈소스 프로젝트를 대표했습니다. 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개 조직은 최대 금액 (1만 5천 달러)의 지원금을 요청하여 받았고 3개 조직은 최소 금액 (5천~7천 달러)을 요청했습니다.
측정항목
프로젝트는 문서 프로젝트의 성공을 측정하는 데 사용한 측정항목을 사례 연구에 설명했습니다.
가장 많이 제안된 측정항목은 다음과 같습니다.
제안된 다른 측정항목은 다음과 같습니다.
- 더 많은 문서 풀 리퀘스트/참여
- 문서 페이지에 대한 더 직접적인 의견
- 페이지에 머문 시간
- 제기된 문제 (사용의 대리 변수)
- 포럼 참여자
- 파트너/자원봉사자/통합 수
- 이탈률 감소
- 커뮤니티의 인지도 향상
기술 문서 프로젝트를 완료하고 우수사례를 제출하는 기간이 짧기 때문에 2022년 대다수의 사용자는 우수사례를 제출할 때 초기 측정항목이 달성되었는지 여부를 판단하기에 충분한 데이터를 수집하지 못했습니다.
2023년에 후속 설문조사의 답변을 받으면 측정항목을 달성했거나 측정항목을 수정한 프로젝트에 관한 정보를 추가하여 이 보고서를 업데이트할 예정입니다.
자세한 내용은 각 조직의 원래 프로젝트 제안서 및 전체 사례 연구로 연결되는 Season of Docs 2022 결과 페이지를 참고하세요.
기술 문서 작성자와 협력
Docs 시즌 프로그램에서는 프로젝트에서 기술 작가를 직접 모집, 인터뷰, 고용, 급여를 지급해야 합니다. 기술 문서 작성자는 GitHub 저장소에서 Season of Docs에서 관리하는 디렉터리에 자신을 추가할 수 있지만 Season of Docs 직원은 기술 문서 작성자를 심사하거나 추천하지 않습니다.
오픈소스 프로젝트에 기술 작가를 고용할 때의 권장사항
프로젝트에 기술 작가를 모집, 채용, 활용하는 데 관한 권장사항을 공유해 달라고 요청했습니다. 인기 추천은 다음과 같습니다.
채용
- 이력서만 검토하는 대신 적은 수의 후보자를 인터뷰하고 실시간 연습 세션을 사용하세요.
- 프로젝트의 언어 또는 도구에 대한 숙련도보다 서면 및 구두 커뮤니케이션 기술을 중시함
- 기술 작가가 프로젝트 작업에 필요한 도메인 지식을 습득하는 방법에 관해 직접 질문합니다.
- 프로젝트의 사명을 열정적으로 지지하고 핵심 오픈소스 가치를 공유하는 사람은 전체 프로젝트를 통해 동기를 유지할 가능성이 더 높습니다.
- 다양한 관점과 배경이 프로젝트에 도움이 되므로 전 세계 지원자를 받아들이세요. 하지만 시간대가 너무나 다른 작가와 멘토가 있으면 원활한 커뮤니케이션을 유지하기 위해 많은 노력이 필요할 수 있습니다.
구인
- 결과물, 지급 일정, 구체적인 시간 약속을 명시한 계약을 사용합니다.
- 프로젝트에 알려지지 않은 사항이 많은 경우 문서 작성과 별도로 발견 또는 연구의 마일스톤을 포함합니다.
조정 및 커뮤니케이션
- 프로젝트에 참여하는 모든 사용자가 맥락과 다음 단계를 더 쉽게 이해할 수 있도록 결정사항을 기록한 회의 로그를 보관합니다.
- 주간 통화, 일일 이메일, 채팅 채널의 상태 업데이트 등 예상되는 커뮤니케이션과 빈도를 명확하게 안내합니다.
- 신속하게 응답하고 '무엇'이 아니라 '왜'를 포함하는 명확한 의견을 제공합니다.
- 기술 문서 작성자를 더 큰 커뮤니티와 연결하여 맥락을 제공하고 작업을 소셜화하세요.
프로세스 및 도구
- 문서 시즌 프로그램 이후에도 지속되고 전체 커뮤니티가 참여할 수 있는 문서화 프로세스 만들기
- 문서 검토는 코드 검토와 마찬가지로 적어도 동일한 시간과 집중력을 필요로 합니다. 충분한 시간을 할애하세요.
일부 권장사항은 명확성을 위해 수정 및 요약되었습니다.
2021년 프로그램과 마찬가지로 2022년 Docs 시즌의 대부분의 기술 작가는 함께 일하는 조직에 직접 지원했습니다.
기술 작가와 협업 시 발생하는 일반적인 문제
2022년 프로그램에서는 테크니컬 라이터와 협업하는 데 문제가 있다는 신고가 줄었습니다. 질병, 정규직 취업, 시간 약속을 지키지 못함으로 인해 기술 작가가 프로그램을 완료하지 못하는 것이 가장 큰 문제였습니다.
한 프로젝트에서는 문서 프로젝트가 Google Summer of Code의 일환으로 진행되는 작업에 종속되어 있고 이러한 종속 항목을 관리하기 어렵다고 신고했습니다. 기술 작가가 문서화해야 하는 하드웨어가 작가의 국가 국방부에서 압수하여 가져올 수 없는 문제가 발생한 프로젝트도 있었습니다.
후속 설문조사
2022년 참여자에게 2023년 5월, 8월, 11월에 후속 설문조사 3개가 전송됩니다. 결과가 들어오면 이 섹션을 업데이트할 예정입니다.
향후 질문
항상 그렇듯이 오픈소스 문서에 대해 더 많이 알수록 더 많은 것을 배우고 싶습니다.
향후 시즌에는 다음과 같은 목표를 달성하고자 합니다.
- 프로젝트 메타데이터를 더 수집하여 프로젝트 연령, 커뮤니티 규모 또는 언어와 문서 요구사항 간의 상관관계를 확인합니다.
- 문서 프로젝트를 분석하여 공유 가능한 템플릿으로 일반화할 수 있는지 확인
- 오픈소스 프로젝트의 기술 작가를 인터뷰하기 위한 평가표 개발
조사하고 싶은 질문이 많지만, Season of Docs에 참여하는 오픈소스 프로젝트 관리자와 유지보수자의 시간을 존중하고자 합니다. 이 프로그램의 최우선 과제는 문서를 통해 프로젝트의 문제를 해결하는 것입니다.