2021년 우수사례 보고서

현재 단계:
2021년 Season of Docs 프로그램은 2021년 12월 14일에 종료되었습니다. 타임라인을 참고하세요.

참고: 이 보고서는 원래 프로그램 신청서 및 조직의 최종 케이스 스터디의 데이터를 요약한 것입니다. 전체 우수사례는 2021년 Docs 시즌 결과 페이지에서 링크됩니다.

Season of Docs 정보

Season of Docs는 Google 오픈소스 프로그램 사무국에서 관리하는 지속가능성 프로그램입니다. Season of Docs의 목표는 다음과 같습니다.

  • 문서를 통해 프로젝트 문제를 해결할 수 있도록 오픈소스 프로젝트 지원
  • 기술 문서 작성자에게 오픈소스 경험을 제공합니다.
  • 오픈소스, 문서, 기술 문서에 대한 인식 제고
  • 오픈소스 문서에서 효과적인 측정항목에 관한 정보를 수집하고 공유합니다.

Season of Docs에 대한 자세한 내용은 프로그램 웹사이트에서 확인할 수 있습니다.

2021년 프로그램 개요

2021년 프로그램 변경사항

2019년과 2020년에는 조직과 기술 작가가 각각 Docs Season 프로그램에 별도로 신청했으며, Docs Season 프로그램 관리자가 기술 작가를 조직과 매칭했습니다. 조직에서는 테크니컬 라이터와 함께 작업할 수 있도록 멘토를 제공하고, 테크니컬 라이터는 위치에 따라 작업물에 대한 보조금을 받았습니다. 이 프로그램에서는 기술 작가, 멘토, 조직 관리자가 프로그램 참여에 만족하는지 측정했지만 문서 작성 결과는 측정하지 않았습니다.

2021년, Season of Docs팀은 문서 작성 결과 측정에 초점을 맞추고 조직과 기술 작가가 더 유연하게 활동할 수 있도록 프로그램을 대대적으로 변경했습니다.

  • 예산 및 제안된 측정항목을 포함하여 프로젝트 제안서를 제출한 조직
  • 기술 작가가 더 이상 Google을 통해 조직에 매칭되지 않고 수락된 조직에 직접 적용됨
  • 선정된 조직은 Open Collective를 통해 보조금을 받았으며, 이를 기술 작가에게 지급했습니다.
  • 기술 작가의 보상은 조직에서 설정함
  • 조직이 최종 평가 및 사례 연구를 제출하고 후속 설문조사에 응답함

2021년 일반 조사 결과

조직

  • 2021년 프로그램의 변경으로 인해 신청하는 조직의 수가 줄었지만 (2021년 신청 조직 수가 2020년보다 30% 감소) 2021년 조직 관리자의 프로그램 만족도가 2020년 관리자보다 약간 높았습니다 (93% 대 91%).

문제, doctypes, 측정항목

  • 대부분의 프로젝트는 문제/질문 감소를 통해 유지보수자의 부담을 줄이거나 프로젝트 사용자 또는 참여자의 프로젝트 참여를 늘리기 위한 문서 작성에 중점을 두었습니다.
    • 승인된 조직의 50% 가 튜토리얼 또는 방법 콘텐츠를 제작했습니다.
    • 승인된 조직의 50% 이상이 현재 문서가 부족하거나 정리되지 않았거나 오래된 문서라고 생각했습니다.
  • 프로젝트에서는 일반적으로 상호작용을 통해 문서의 효과를 측정하고자 했습니다. 특히 제기된 문제가 줄어들고 문서 방문자 수와 프로젝트 참여가 늘어난 것이죠.
  • 2022년 11월 현재 30개 프로젝트 중 25개 프로젝트가 응답했으며, 응답한 프로젝트의 결과는 다음과 같습니다.
    • 기존 측정항목을 충족했다고 응답한 프로젝트 18개
    • 5개 프로젝트가 수정된 측정항목을 충족했습니다.
    • 프로젝트 2개가 아직은 이르다고 밝혔음

프로그램 참여

  • 테크니컬 라이터를 모집, 채용하고 비용을 지불하는 일은 조직 관리자에게 이 프로그램에서 가장 어려운 부분이었습니다.
  • 2022년 11월 현재 30개 조직 중 24개 조직이 응답했으며 그 결과는 다음과 같습니다.
    • 18개 조직은 문서 시즌 기술 작가와 계속해서 협력하고 있습니다 (계속적인 참여자 또는 질문에 답변하는 리소스).
      • 4개 조직이 Season of Docs 기술 작가와 함께 유료로 작업했습니다.

2021년 하이라이트

  • 여러 프로젝트에서 테크니컬 라이터가 Season of Docs 프로그램 종료 후에도 프로젝트 작업을 계속할 의향이 있다고 밝혔습니다.
  • Metanorma에는 자격 요건을 갖춘 기술 작가가 너무 많이 지원하여 프로그램 기간 동안 Docs 시즌 지원 작가와 함께 작업할 추가 작가를 고용할 수 있는 매칭 자금을 찾았습니다.
  • Moja Global은 문서에 대한 커뮤니티의 참여도가 높다는 사실을 확인하고 더 많은 참여자가 프로젝트 문서에 참여할 수 있도록 새로운 문서 작업 그룹을 구성했습니다.

2021년 요약 데이터

2021년에는 82개 조직과 30개의 오픈소스 조직이 프로그램에 지원했습니다. 선택 기준은 애플리케이션 만들기 가이드를 참고하세요. 참여하는 조직의 전체 목록은 Season of Docs 웹사이트에서 확인할 수 있습니다. 승인된 30개 조직 모두가 2021년 프로그램 참여를 완료하기 위해 최종 우수사례 보고서를 제출했습니다.

조직 정보

2021년 Season of Docs에 참여한 조직은 다양한 오픈소스 프로젝트를 대표했습니다. 2021년 사용자 집단은 다음과 같습니다.

  • Julia, Perl, R과 같은 대규모 언어 프로젝트
  • 교육, 기후, 핀테크, 의료, 도서관 서비스, 머신러닝, 질량 분광법, 공공 계약, 로봇 공학 관련 프로젝트
  • 카오스 엔지니어링 도구, 퍼저, 챗봇 SDK, 소프트웨어 구성 분석 파이프라인, 성능 모니터링 도구, 시각적 프로그래밍 도구 등 개발자 중심 프로젝트
  • RedoclyMetanorma와 같은 문서 도구용 문서 프로젝트

Python 생태계 프로젝트가 가장 큰 하위 카테고리였습니다. 2021년에는 ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite, SymPy가 포함되었습니다.

Google은 프로젝트에 대한 메타데이터 (창립일, 참여자의 지리적 분포, 참여자 수, 사용자층 규모 등)를 수집하지 않았습니다.

Google은 프로젝트에 사용한 오픈소스 라이선스를 표시하도록 요청했습니다.

각 OSS 라이선스를 사용하는 프로젝트 수를 보여주는 막대 그래프: Apache 2.0: 10개 프로그램, 3절 BSD: 5개 프로그램, MIT: 5개 프로그램, GPL 2.0: 4개 프로그램, LGPL 2.1: 4개 프로그램, Mozilla Public License 2.0: 3개 프로그램, Artistic, Boost 및 2 조항 BSD: 각 프로그램

2021년 조직에서 설명한 문서 문제는 오픈소스 프로젝트와 일반적인 기술 문서 모두에서 매우 흔히 발생하는 문제입니다.

2021년 프로그램에서 조직이 해결하고자 하는 주요 문제는 다음과 같습니다.

조직에서 신고한 문제를 보여주는 막대 그래프: 프로젝트 측면의 특정 사용 사례에 관한 문서가 부족함: 14개 프로젝트, 문서가 정리되지 않음: 14개 프로젝트, 문서가 오래됨: 6개 프로젝트, 문서가 일관되지 않음: 3개 프로젝트, 문서를 다른 도구, 플랫폼 또는 형식으로 변환해야 함: 2개 프로젝트

조직에서 문서 문제를 여러 개 신고할 수 있습니다. 자세한 내용은 각 조직의 전체 우수사례로 연결되는 시즌 of Docs 2021 결과 페이지를 참고하세요.

생성된 문서 유형

2021년 케이스 연구에서 가장 자주 언급된 문서 유형은 튜토리얼이었습니다.

생성된 문서 유형을 보여주는 막대 그래프: 튜토리얼: 프로젝트 9개, 방법: 프로젝트 6개, 시작하기: 프로젝트 3개, 예: 프로젝트 3개, 참조: 프로젝트 3개, API 문서, 동영상, 빠른 시작, 템플릿, 방문 페이지: 각각 프로젝트 2개

케이스 스터디에 언급된 다른 문서 유형에는 Docs-as-code 파이프라인, 다이어그램, 용어집, 스타일 가이드, FAQ, 국제화, Codelab, 콘텐츠 모델, 모듈, 개념 문서, 오류 메시지, 사용자 연구, 리드미, 지식 베이스가 포함되었습니다.

이러한 카테고리 중 일부는 모호하며 하나의 문서 프로젝트에 여러 문서 유형이나 기능이 포함될 수 있습니다.

여러 프로젝트에서 문서 유형을 계획하기 위한 가이드로 Diátaxis 프레임워크를 사용했다고 구체적으로 언급했습니다.

자세한 내용은 각 조직의 전체 우수사례로 연결되는 시즌 of Docs 2021 결과 페이지를 참고하세요.

예산

2021년 평균 예산 요청은 10,200달러였으며 중앙값은 10,000달러였습니다. 세 개의 조직만 최대 금액 (15,000달러)의 지원금을 요청하고 받았으며, 세 개의 조직은 최소 금액 (5,000달러)의 지원금을 요청했습니다.

측정항목

프로젝트는 문서 프로젝트의 성공을 측정하는 데 사용한 측정항목을 사례 연구에 설명했습니다.

가장 많이 제안된 측정항목은 다음과 같습니다.

문서 성공 측정항목을 보여주는 막대 그래프: 프로젝트 문제/질문 감소: 13개 프로젝트, 문서/문서 사용 방문자 증가: 9개 프로젝트, 참여자/풀 리퀘스트 증가: 8개 프로젝트, 문서 풀 리퀘스트/참여도 증가: 7개 프로젝트, 생성된 문서 총 개수: 5개 프로젝트, 문서 만족도 증가 (설문조사 통해), 프로젝트 사용 증가, 문서 페이지에 대한 직접적인 의견 증가: 각 4개 프로젝트, SEO 개선: 3개 프로젝트, 전환된 문서 총 비율 및 문서에서 다루는 타겟 정보 총 비율: 각 2개 프로젝트

제안된 다른 측정항목에는 GitHub 별표, 페이지에 머문 시간, 메일링리스트 전환, 정성적 사용자 테스트, 포럼 참여자 수, 파트너/자원봉사자/통합 수가 포함되었습니다.

기술 문서 프로젝트를 완료하고 우수사례를 제출하는 기간이 짧아 2021년 사용자 집단의 대부분은 초기 측정항목이 달성되었는지 여부를 판단하기에 충분한 데이터를 수집하지 못했습니다.

자세한 내용은 각 조직의 전체 사례 연구로 연결되는 Season of Docs 2021 결과 페이지를 참고하세요.

기술 문서 작성자와 협력

2021년 Season of Docs 프로그램의 가장 큰 변화는 테크니컬 라이터와 프로젝트를 진행하는 방식에 관한 것이었습니다. 이전 시즌에는 테크니컬 라이터가 Google에 직접 지원하여 프로그램 관리자와 프로젝트를 연결시켜 Google로부터 직접 정액제를 지급받았습니다.

2021년에는 기술 문서 작성자가 프로젝트에 직접 지원했으며 프로젝트에서 기술 문서 작성자 보상에 대한 예산을 설정하고 Docs 시즌 Open Collective 펀드를 통해 지급했습니다.

2021년 프로그램에 참여한 대부분의 프로젝트는 기술 작가를 모집하거나 고용하는 데 대한 경험이 거의 없거나 전혀 없었으며, 많은 프로젝트에서 이 절차가 더 많은 지원이 필요한 부분이라고 지적했습니다. 이러한 의견에 따라 Season of Docs팀은 프로그램 가이드에 기술 작가 계약 작성을 위한 문서를 추가했습니다.

채용 추천

프로젝트는 시즌 오브 문서에 참여하고자 하는 다른 프로젝트를 추천해 달라는 요청을 받았습니다. 가장 많이 추천된 채용 추천은 다음과 같습니다.

  • 프로그램에 참여하기 전이라도 기술 작가를 위한 모집 자료를 최대한 빨리 공유하세요. 커뮤니티에 추천 후보를 요청합니다.
  • 프로젝트 채널 외부에 널리 공유합니다. 포용적인 표현을 사용하고 소외된 계층의 지원자를 직접적으로 독려합니다.
  • 문서 작성 프로세스에 필수적인 도구를 파악하고 이러한 도구를 사용하는 데 경험이 있는 기술 작가를 모집합니다.
  • 기술 문서 작성자에게 결과물 및 주요 목표, 커뮤니케이션 채널 및 확인, 결제 절차 및 시점에 대한 명확한 기대치를 설정합니다.
  • Docs 시즌 테크니컬 라이터를 통해 멘토링과 코칭을 제공하여 커뮤니티 회원에게 투자하고 테크니컬 라이터로서 성장하도록 지원해 보세요.
  • 특히 테크니컬 라이터가 프로젝트 영역에서 사전 경험이 없는 경우 테크니컬 라이터 온보딩, 질문에 답변 및 지원 제공에 예상보다 많은 시간을 할애하세요.
  • 향후 프로젝트에 사용할 수 있도록 채용, 고용, 온보딩 프로세스를 문서화합니다.

기술 작가 후보의 출처를 보여주는 막대 그래프: 프로그램에 직접 신청: 7명, SoD GitHub 또는 이전 SoD 참여자: 4명, Write the Docs Slack 또는 커뮤니티 회원: 각 3명, 구인 사이트 (Upwork, LinkedIn) 또는 Google Summer of Code 또는 Code-In 졸업생을 통해 신청: 각 2명

참고: 기술 작가 후보를 모집한 사례 연구에 표시된 프로젝트는 아닙니다.

테크니컬 라이터와 작업할 때 발생하는 일반적인 문제

기술 작가 문제를 보여주는 막대 그래프: TW 이탈: 8개 프로젝트, 커뮤니케이션 문제: 6개 프로젝트, TW 온보딩: 4개 프로젝트, TW 모집, 채용 또는 지급, 프로젝트 도구 설정: 각각 3개 프로젝트

코로나19 또는 기타 질병, 팬데믹과 관련된 가족 책임으로 인해 여러 프로젝트의 기술 작가가 참여를 중단해야 했습니다. 일부 프로젝트에서는 시간대 불일치 또는 인터넷 연결 문제와 관련된 커뮤니케이션 문제가 발생했다고 신고했습니다.

프로젝트에서 커뮤니티에 온보딩하거나 프로젝트의 문서 도구 모음을 설정하는 데 따르는 어려움을 과소평가한 것으로 나타났습니다.

일부 프로젝트는 Open Collective에 은행 문제가 있거나 작가의 거주 국가에 결제 제한이 있어 테크니컬 라이터에게 보급이 지연되는 경우가 있었습니다.

Open Collective 수수료에 관한 프로그램 문서가 명확하지 않았습니다. Google은 프로젝트에 대한 초기 송금에 대한 Open Collective 거래 수수료를 부담했지만 다른 결제 채널 (예: 통화 변환 수수료)에서 부과하는 거래 수수료는 부담하지 않았습니다. 향후 프로그램의 문서에서 이 내용을 더 명확하게 설명할 수 있도록 노력하겠습니다.

후속 설문조사

Docs 시즌 프로그램의 일환으로 프로젝트에 후속 설문조사 참여를 요청했습니다. 2022년 5월, 8월, 11월에 설문조사를 3번 보냈습니다.

후속 설문조사의 응답 수를 보여주는 막대 그래프: 5월 설문조사: 13개 응답, 8월 설문조사: 21개 응답, 11월 설문조사: 12개 응답

후속 설문조사에서는 프로젝트에 제안서 및 사례 연구 링크가 여전히 활성 상태인지 확인해 달라고 요청했습니다. 설문조사에는 프로젝트의 성공 (우수사례에 설정된 측정항목에 따라 결정됨)과 프로젝트 기술 작가의 지속적인 참여 및 보상에 관한 질문도 포함되었습니다.

  1. 아직도 Docs 시즌 기술 작가와 협업 중이신가요?

설문조사에 따르면 테크니컬 라이터의 지속적인 참여를 보여주는 막대 그래프: 5월에는 6개 프로젝트에서 테크니컬 라이터가 참여하거나 질문에 답했으며, 1개 프로젝트는 진행 중인 테크니컬 라이터의 개입이 없었습니다. 8월에는 11개 프로젝트에서 테크니컬 라이터가 참여 중이었으며, 7개 프로젝트에서는 테크니컬 라이터가 참여하지 않았고, 3개 프로젝트에서는 테크니컬 라이터가 질문에 답변했습니다. 11월에는 5개 프로젝트에서 테크니컬 라이터가 계속 참여하고 있다고 보고했으며, 3개 프로젝트에서는 테크니컬 라이터가 참여하고 있지 않다고 보고했으며, 4개 프로젝트에서는 테크니컬 라이터가 질문에 답변하고 있다고 보고했습니다.

  1. 기술 문서 작성자가 아직 프로젝트에 참여하고 있다면 어떤 식으로든 보상을 받고 있나요?

각 설문조사에서 기술 작가의 프로젝트 보상을 보고한 프로젝트 수를 보여주는 막대 그래프입니다. 5월에는 5개 프로젝트에서 기술 작가에게 진행 중인 작업에 대한 보수가 지급되고 있다고 신고했으며, 4개 프로젝트에서는 기술 작가에게 보수가 지급되지 않는다고 신고했습니다. 8월에는 4개 프로젝트에서 기술 작가에게 금전적 보상을 제공한다고 보고했으며 7개 프로젝트에서는 기술 작가에게 금전적 보상을 제공하지 않는다고 보고했습니다. 11월에는 기술 작가에게 급여를 지급한다고 보고한 프로젝트가 2개, 기술 작가에게 급여를 지급하지 않는다고 보고한 프로젝트가 5개 있었습니다.

  1. 이 시점에서 문서 프로젝트가 성공적이라고 생각하시나요?

각 설문조사에서 측정항목을 기준으로 성공 여부를 보고하는 프로젝트 수를 보여주는 막대 그래프입니다. 5월에는 6개 프로젝트에서 측정항목이 충족되었다고 보고했으며, 6개 프로젝트는 아직 판단하기 이르다고 말했고, 2개 프로젝트는 조정된 측정항목을 충족했다고 말했습니다. 8월에는 16개 프로젝트에서 측정항목이 충족되었다고 보고했으며, 3개 프로젝트에서는 조정된 측정항목이 충족되었다고 보고했으며, 2개 프로젝트에서는 아직 판단하기 이르다고 보고했습니다. 11월에 프로젝트 9개는 측정항목이 충족되었음을 보고했고, 프로젝트 3개는 조정된 측정항목이 충족되었다고 보고했으며, 아직 말하기가 이르지 않은 프로젝트는 보고되지 않았습니다.

향후 질문

항상 그렇듯이, 오픈소스 문서에 대해 더 많이 배울수록 더 많은 것을 배우고 싶습니다! 향후 시즌에는 다음과 같은 정보를 얻고자 합니다.

  • 프로젝트 도메인이 doctype 선택 또는 측정항목 선택과 상관관계가 있는지 여부
  • 프로젝트 완료 및 기술 문서 작성자 유지에 가장 효과적인 기술 문서 작성자 채용 및 온보딩 관행
  • 문서 효과성을 측정하기 위한 합리적인 일정

조사하고 싶은 질문이 많지만, Season of Docs에 참여하는 오픈소스 프로젝트 관리자와 유지보수자의 시간을 존중하고자 합니다. 이 프로그램의 최우선 순위는 문서 문제 해결을 위한 프로젝트를 지원하는 것입니다.