현재 단계:
문서 개발 타임라인을 참고하세요.
이 예시를 사용하여 자체 우수사례 보고서를 작성하세요.
PicklePlus: GloriousPickle 참여 도구 문서화
조직 또는 프로젝트: Glorious Pickle 조직 또는 프로젝트의 기본 사이트 링크
조직 설명: GloriousPickle (현재 버전 1.2.3, 2009년 첫 번째 버전)은 단 한 마리의 아기 오이부터 컨테이너 운송에 이르기까지 가능한 모든 절임 가능 채소의 소금, 설탕, 식초, 향신료의 완벽한 비율을 쉽게 계산할 수 있는 MIT 라이선스 라이브러리입니다.
작성자: 선택사항: 우수사례의 저자 나열, 요청 시 사용자 이름 사용
문제 기술서/제안 요약
새롭거나 개선된 문서로 어떤 문제를 해결하려고 하셨나요? 가능한 경우 프로젝트 사이트의 제안서 페이지로 연결합니다.
GloriousPickle 도구 요소 데이터베이스에 재료를 추가하는 작업은 시간이 많이 걸리고 복잡하며 도구에는 제대로 된 문서화가 없습니다. git을 사용하거나 pull 요청을 해 본 경험이 없는 참여자도 많습니다. 즉, GloriousPickle의 성분 데이터에 심각한 격차가 있고 도구의 유용성이 떨어집니다. 새로운 재료 추가에 관한 문서를 개선하여 신규 참여자와 피클링을 더 많이 장려할 수 있기를 바랍니다!
프로젝트 설명
제안서 만들기
Google Docs 시즌에 대한 제안을 어떻게 작성하게 되었나요? 조직에서 아이디어를 결정하기 위해 어떤 절차를 사용했나요? 어떻게 의견을 구하고 통합했나요?
GloriousPickle PickleDocs SIG는 Google Open Source Programs Office의 트윗을 통해 Google Season of Docs 프로그램에 대해 알게 되었습니다. SIG는 격주 회의에서 이 프로그램에 대해 논의하고 제안서를 작성하는 데 동의했습니다. SIG의 두 멤버 (@KimChiCook 및 @Dillicious)는 다음 회의에서 검토할 수 있도록 초안 제안서 작성에 자발적으로 참여했습니다.
PickleDocs SIG가 제안 초안에 동의하면 전체 프로젝트에 의견을 요청하는 이메일이 전송되었습니다. 식재료 추가 API의 유지관리 담당자인 @GloriousPicklePat을 비롯한 14명의 커뮤니티 회원이 의견을 제공했습니다. @GloriousPicklePat은 이 프로그램에 자원하여 자원했습니다.
받은 의견을 논의하고 반영한 후 제안서를 GloriousPickle 프로젝트 운영 위원회에 보내 투표를 실시했습니다. GPPSC의 5개 회원 모두가 제안 및 신청서 제출에 +1을 했고 @VinegarViv는 프로그램 참여 및 지급을 감독하는 데 필요한 Open Collective 계정 생성을 돕는 데 동의했습니다.
예산
예산에 간단한 섹션을 넣습니다. 작업을 어떻게 추정하셨나요? 예상치 못한 비용이 있었나요? 지원금 지급액보다 적은 금액을 지출하셨나요? 자금을 적절하게 할당했나요, 아니면 일부 항목의 예산을 더 많이/적거나 필요 없었나요? Google Season of Docs 외에 사용할 수 있는 다른 자금이 있었나요?
GloriousPickle PickleDocs SIG 회원 2명은 테크니컬 라이터로 활동하고 있습니다 (한 명은 유럽, 한 명은 아르헨티나에서). 그들은 우리가 작업을 추정하고 유사한 프로젝트 예산을 찾는 데 도움이 되었으며, 이전에 수행한 제안서 초안 작업을 비교하는 데 도움이 되었습니다. 또한 프로젝트에 할당한 2019 PicklePals 컨벤션에서 발생한 무제한 스폰서십 자금(미화 1,000달러)도 남아 있었습니다.
산불 피해를 입고 집에서 인터넷을 사용할 수 없는 지역에서 테크니컬 라이터가 Wi-Fi 핫스팟을 임대하는 데 예상치 못한 비용이 발생했습니다. 또한 참가자들에게 발송하는 티셔츠 수가 계획한 것보다 줄었기 때문에 균형을 이루게 했습니다.
또한 GloriousPickle 기고자인 @Piccalily (피클을 쉬던 시절 전문 카피라이터였던 분)에게 이 테크니컬 라이터가 작성한 문서의 카피편집과 교정을 지원하기로 했습니다.
참여자
이 프로젝트에 누가 참여했나요 (참가자가 요청할 경우 사용자 이름 사용)? 테크니컬 라이터를 어떻게 찾고 고용했나요? 다른 자원봉사자나 유료 참여자는 어떻게 찾으셨나요? 어떤 역할을 맡았나요? 중도 포기한 사람이 있나요? 채용, 커뮤니케이션, 프로젝트 관리에 대해 무엇을 배웠나요?
이 프로젝트를 위해 작업한 핵심 팀은 다음과 같습니다.
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (관리자 도움말, GPPSC)
- @BBChips, @GloriousPicklePat (주제별 전문가)
- 샘 스크리브 (테크니컬 라이터)
Google Season of Docs GitHub 저장소 목록을 통해 샘 스크립을 찾았습니다. 샘은 요리 잡지 회사에서 일하고 웹사이트 문서를 작성했던 경력이 우리 프로젝트와 잘 어울린다고 생각했습니다. Sam은 격주로 진행되는 PickleDocs SIG 회의에 참석하여 프로젝트에 관해 대화를 나누면서 제안에 반영한 몇 가지 매우 가치 있는 제안을 했습니다. SIG 회원의 네트워크를 통해 알려진 다른 2명의 테크니컬 라이터에게도 연락을 취했으나 프로그램 기간 동안 둘 다 연락을 받지 못했습니다.
샘의 시간대가 대부분의 PickleDocs SIG 회원과 몇 시간밖에 겹치지 않기 때문에, 샘의 시간대에 거주하며 재료 추가 과정에 익숙한 Picklers를 대상으로 토론 포럼에 전화 연락을 했습니다. @BBChips는 자발적으로 샘에게 질문에 답하고 필요에 따라 다른 전문가를 찾는 데 도움을 주었습니다. @GloriousPicklePat은 또한 샘이 도구의 기본 아키텍처와 API에서 발생할 수 있는 오류 메시지를 이해하는 데 도움을 주고 GitHub 및 git 도움말도 제공했습니다.
안타깝게도 프로그램 도중에 @VinegarViv가 개인적인 이유로 프로젝트에서 물러나야 했습니다. GPPSC 회원인 @GherKen은 관리 및 지급과 관련된 질문을 처리하기 위해 발을 디뎠습니다.
일부 놓친 질문 (GloriousPickle에서 무료 Slack 인스턴스를 사용하며 토론이 너무 빠르게 진행되어 롤링 보관처리 제한으로 인해 대화가 누락되는 경우도 있음)을 확인한 후 실행 중인 질문 목록을 공유 문서에 보관해야 한다는 사실을 알게 되었습니다 (공유 Google 문서 사용). PickleDocs SIG 회원은 각 회의 전에 점검을 점검하고 회의가 끝나기 전에 답변을 받았습니다. 샘은 긴급한 질문을 위해 @BBChips를 직접 핑할 수 있었습니다.
샘, 샘과 함께 작업하면서 매우 만족스러웠습니다. GloriousPickle 문서를 업데이트하는 것 외에도 샘과 샘이 열정적인 선택 도구가 되었습니다.
타임라인
프로젝트 일정을 간략하게 설명합니다 (프로젝트가 진행 중인 경우 예상 종료일 또는 중간 마일스톤 명시).
Google Season of Docs 프로그램에서 참여 조직을 발표하기를 기다리는 동안 PickleDocs SIG 회원들은 샘에게 유용할 것으로 생각되는 이전 작업을 검색했습니다. 한 달 동안 중단된 문서를 업데이트하려는 이전 노력에서 몇 가지 참고사항을 발견했으며, Google 오픈소스 저장소에 있는 문서 성숙도 감사 자료의 일부를 검토하기도 했습니다.
Google Season of Docs에 선정되었다는 좋은 소식을 듣게 된 후 Sam과 PickleDocs SIG는 만나서 대략적인 일정을 세웠습니다.
| 단계 | 완료자 |
|---|---|
| 문서 감사 검토 | 5월 7일 |
| 마찰 로그 3 사용 사례 | 5월 14일 |
| @GloriousPicklePat 및 @BBChips로 마찰 로그를 검토하고 질문에 답하세요 | 5월 28일 |
| 업데이트된 문서 사용 사례 1의 초안 | 6월 25일 |
| @GloriousPicklePat 및 @KimChiCook에서 검토한 사용 사례 1 초안 | 7월 2일 |
| 업데이트된 문서 사용 사례 2의 첫 번째 초안 | 7월 2일 |
| @GloriousPicklePat 및 @Dillicious의 사용 사례 2 초안 검토 | 7월 9일 |
| 업데이트된 문서 사용 사례 3의 첫 번째 초안 | 7월 9일 |
| @Dillicious 및 @KimChiCook의 사용 사례 3 초안 검토 | 7월 16일 |
| 모든 사용 사례에서 답변이 제공되는 모든 쿼리 | 7월 30일 |
| 대부분의 PickleDocs SIG는 8월 1~20일 휴가 중이었습니다. | -- |
| 커뮤니티에서 새 문서 테스트 시작 (GloriousPickle 사이트에 초안으로 게시된 문서) | 8월 21일 |
| 테스트 의견 통합됨 | 9월 10일 |
| 새 문서의 복사 및 교정 | 9월 17일 |
| 문서의 초안 상태 삭제됨, 문서 공식 출시 | 9월 28일 |
| 생성된 문서의 업데이트 프로세스 | 11월 1일 |
| 이 우수사례는 | 11월 8일 |
| 우수사례 제출됨 | 11월 16일 |
제안서 예산에서 테크니컬 라이터가 주당 10~15시간을 프로젝트 작업에 사용할 것으로 예상했습니다. 샘은 활동 시간을 기록하며 주당 평균 11.5시간을 기록했습니다.
결과
어떤 내용이 생성, 업데이트 또는 변경되었나요? 가능한 경우 게시된 문서에 대한 링크를 포함합니다. 제안서에 생성되지 않은 결과물이 있었나요? 이러한 항목도 나열하세요.
세 가지 주요 사용 사례가 전체 사용자 안내 가이드와 함께 문서화되었습니다.
GloriousPickle에 새 재료 추가하는 방법
GloriousPickle에 변형 재료를 추가하는 방법
GloriousPickle에서 재료를 업데이트하거나 수정하는 방법
이 가이드에는 더 쉽게 참여할 수 있도록 하는 새로운 pull 요청 템플릿도 포함되어 있습니다.
또한 프로젝트를 진행하는 동안 샘은 학습한 용어가 모인 간단한 Pickle 용어집을 만들었고, 이 용어집은 GloriousPickle 프로젝트 사이트에도 게시되었습니다.
프로젝트 위키에 사용자 안내 가이드를 업데이트하는 방법을 추가했습니다.
우리는 GitHub 신규 참여자를 위한 요약본을 만들어 프로세스와 도구를 사용하는 데 도움을 주었지만, 사용 가능한 리소스를 확인한 후 다른 프로젝트의 요약본을 대신 사용할 수 있었습니다.
측정항목
프로젝트의 성공을 측정하기 위해 어떤 측정항목을 선택했나요? 이러한 측정항목을 수집할 수 있었나요? 측정항목이 프로젝트에 대해 원하는 결과와 얼마나 관련성이 높은가? 제안 이후 측정항목이 변경되었나요?
제안서에서는 다음 두 가지 측정항목을 제안했습니다.
- 재료 관련 pull 요청 수
- 새 참여자의 pull 요청 수
문서 초안을 게시한 후 첫 한 달인 9월에는 재료 관련 pull 요청이 5% 증가했으며(8월에는 20개에서 9월 21개로) 총 4개의 pull 요청을 한 새로운 기여자는 3명(8월에 2개의 pull 요청을 한 신규 참여자 2명)에 비해 3명 증가했습니다. 이러한 지표는 매월 추적할 계획입니다.
또한 1월 1일부터는 문서가 게시된 후 분기별로 3회 이상 참여한 참여자의 수도 추적할 예정입니다.
일례로, 이 새로운 문서 덕분에 새로운 기여자가 GloriousPickle 재료 데이터베이스를 추가할 수 있게 되었다고 생각합니다. 새로운 기여자는 이전에 시도했지만 프로세스를 이해하지 못해 업데이트를 완료하지 못했다고 PR 댓글에서 언급했습니다.
분석
어떤 점이 좋았나요? 예상과 다른 점은 무엇이었나요? 어떤 장애물이나 차질을 겪으셨나요? 프로젝트가 성공적이라고 생각하십니까? 그 이유는 무엇인가요? (조금이 늦은 경우 프로젝트의 성공 여부를 판단할 수 있을 것으로 예상되는 시기를 설명하세요.)
저희는 Google Season of Docs 프로젝트의 결과에 매우 만족하며 이 프로젝트는 성공적이라고 생각합니다. 새로운 문서는 명확하고 유용하며, 재료와 관련된 pull 요청 수와 새로운 참여자의 pull 요청 수가 이미 늘었습니다.
또한 원래 제안서에 대한 의견을 제공하고 새 문서를 초안 형태로 테스트하면서 거의 모든 GloriousPickle 커뮤니티가 참여했습니다.
우리는 몇 가지 예상치 못한 장애물을 마주쳤습니다. 우리는 샘 주에서 발생한 산불이 인터넷 중단만큼 더 큰 피해를 입히지 않았다는 점에 감사하고 있었습니다. 또한 프로젝트에서 @VinegarViv를 잃고 아쉽습니다. 그녀와 가족의 행운을 기원하며 곧 다시 만나기를 바랍니다.
샘이 이 문서 작업을 시작할 때까지 우리가 깨닫지 못했던 한 가지는 피클 관련 배경지식 없이 프로젝트에 참여하는 사람에게 피클 관련 용어와 두문자어가 얼마나 많이 생겨났는지였습니다. 하지만 샘은 익숙하지 않은 용어의 목록을 모두 보관하고 자체 연구를 통해 해당 용어를 정의하고 커뮤니티 회원에게 설명 및 참조를 요청했습니다. 이 피클 용어집은 향후 피클링 커뮤니티의 더 많은 사람들을 환영하는 데 큰 도움이 될 것입니다.
요약
프로젝트 경험을 2~4개 단락으로 요약하세요. 배운 내용과 향후 다르게 대처할 방법을 강조합니다. 문서화와 관련된 문제를 해결하려는 다른 프로젝트에 어떤 조언을 하고 싶으신가요?
한마디로 말로 하면 엄청난 경험을 할 수 있답니다. 문서 결과물을 달성했고 측정항목이 목표에 부합하는 것 같습니다.
테크니컬 라이터인 Sam Scribe와 함께 작업한 것은 운이 좋았던 것이 이 프로젝트의 성공에 큰 힘이 되고 있습니다. [내가 작성한 게 아님—Sam] 샘은 피클링이나 GitHub 사용 경험은 없지만 숙련된 테크니컬 라이터로서 새로운 분야에 뛰어들고, 질문하고, 연구하는 데 편안함을 느꼈습니다. 샘은 프로젝트 도구 (간반 보드를 사용하여 작업 추적)뿐 아니라 피클 농담도 빠르게 익혔습니다. 샘이 절인 곤충을 잡았고 커뮤니티에서 병에 넣은 것을 매우 기쁘게 생각합니다.
다른 프로젝트에는 다음과 같이 하는 것이 좋습니다.
- 제안서는 작고 관리하기 용이합니다. (원래는 에스티메이터와 산업용 일괄 절임 기계를 함께 사용하기 위한 문서를 제안에 포함하려고 했는데, 오픈소스 피클 기계에 깊이 관여하는 커뮤니티 회원 중 한 명이 프로그램 기간 동안 박사 논문을 작성할 예정이었기 때문에 빠뜨렸습니다.) 결국 샘을 바쁘게 보낼 만큼 해야 할 일이 많아졌습니다.
- 테크니컬 라이터를 구할 때는 인맥을 활용하세요. 커뮤니티의 모든 구성원에게 추천을 요청하세요. Docs GitHub의 Google Season을 통해 Sam을 찾았지만 신청 기간 동안 여러 사람과 이야기를 나누었기 때문에 자신감 있게 협업할 수 있었습니다.
- 커뮤니티에 가입한 테크니컬 라이터를 환영해 주세요. 샘은 GloriousPickler의 열정적인 태도로 쉽게 질문할 수 있었다고 말합니다.
- 테크니컬 라이터가 오픈소스 기술을 익히도록 지원합니다. Sam은 이전에 git을 사용한 적이 없지만 몇 가지 튜토리얼을 진행한 후 빠르게 익혔습니다. 처음에 샘은 커뮤니티에서 얻을 수 있는 의견의 양과 이를 통합하는 방법에 대해 걱정했지만, 커뮤니티의 '대략적인 합의' 모델 ('모든 문제가 해결되었지만 반드시 수용되지는 않을 때 합의가 이루어짐') 덕분에 샘은 기술 글쓰기 전문 지식을 사용하여 비판에 자신 있게 대응할 수 있었습니다.
부록
공유하고자 하는 테크니컬 라이터와 협력하기 위한 계약서나 문서 프로젝트용 템플릿 또는 기타 공개 문서 리소스에 연결하려는 다른 자료가 있는 경우 여기에 해당 자료를 나열하고 연결할 수 있습니다. 또한 부록은 사용한 문서 도구 또는 리소스의 링크를 나열하거나 위 섹션에 적합하지 않을 수 있는 감사 또는 감사 인사를 추가할 수 있는 좋은 장소입니다.
감사의 말
Google Play팀에서 다음 분들께 감사의 말씀을 전합니다.
- @Dillicious는 파트너와 로우파이 힙합 라디오에게도 감사를 전합니다.
- @KimChiCook은 피클하는 방법을 가르쳐 주신 할머니에게 감사의 말을 전합니다.
- @Piccalily는 Chicago Manual of Style Online에 감사드립니다.
- @GherKen은 만들 수 있는 피클을 모두 먹어 준 세 아이에게 감사의 말을 전합니다.
- @VinegarViv가 퇴사하는 것을 수용해 준 나머지 팀원들에게도 감사의 말을 전합니다.
- @BBChips는 피클이 아닌 최고의 음식인 Tunnock의 캐러멜 웨이퍼에 감사를 표합니다
- @GloriousPicklePat은 이 프로젝트에 참여해 주신 PickleDocs SIG에 감사의 마음을 전합니다.
- 샘 스크리브는 GloriousPickle 커뮤니티 전체, 특히 2021년 여름 항아리가 부족할 때 통조림 병을 보내준 Pickler에게 감사의 말을 전합니다. 이 병에서 맛있는 피클을 여러 개 구하기 시작했습니다.