현재 단계:
2019년 Docs 시즌 프로그램은 2020년 3월 6일에 종료되었습니다. 타임라인을 참고하세요.
이 페이지는 올해 문서 시즌의 작업을 마친 후 프로젝트 보고서를 작성하는 방법에 대한 테크니컬 라이터를 위한 가이드라인을 제공합니다.
프로젝트 보고서 제출
프로젝트 완료 단계가 시작되면 테크니컬 라이터 가이드의 프로젝트 완료 섹션에서 제공되는 양식을 작성하여 프로젝트 보고서를 제출할 수 있습니다.
프로젝트 보고서에 포함할 정보
이 섹션에서는 프로젝트 보고서에 제공할 수 있는 정보 유형을 설명합니다. 프로젝트 보고서 양식에는 자유 텍스트 필드와 객관식 질문이 포함됩니다.
과제로 연결
수행한 작업에 대한 설명으로 연결되는 링크를 제공하세요.
링크는 완료한 작업에 관한 간단한 설명, 오픈소스 프로젝트가 저장소에 병합한 문서, 프로젝트의 현재 상태 요약, 과제 및 학습 내용 목록을 가리켜야 합니다.
이 링크는 웹사이트에 게시된 Docs 시즌 결과에 나타납니다. 게시된 결과는 프로그램 중에 완료한 작업을 보여줍니다. 게시된 결과는 이력서의 일부로 작업을 다시 언급하는 좋은 방법이기도 합니다.
프로젝트 보고서를 제출하기 전에 멘토와 링크를 공유하고 검토를 요청해야 합니다.
프로젝트 보고서 요구사항
다음 요구사항을 고려하세요.
- 링크된 콘텐츠를 통해 Docs 시즌 동안 완료한 작업, 즉 내가 변경한 내용이나 새로 작성한 문서를 쉽게 식별할 수 있어야 합니다.
- 작업은 안정적인 위치에 있어야 합니다. 제출한 후에는 URL을 변경할 수 없습니다.
다른 사용자가 링크의 타겟에 있는 (또는 참조된) 콘텐츠를 사용하여 작업을 빌드할 수 있어야 합니다.
- 작업이 100% 완료되면 다른 사용자가 사용할 수 있습니다.
- 작업이 100% 완료되지 않은 경우 해야 할 일이 명확하게 표시됩니다.
작업을 설명하는 방법의 좋은 예
이러한 작업을 모두 또는 전부 실행할 필요는 없지만 요구사항을 충족할 수 있는 몇 가지 방법은 다음과 같습니다.
수행한 작업과 수행한 커밋 및 작업한 저장소의 링크를 설명하는 블로그 게시물이나 웹페이지 또는 공개 GitHub gist를 만듭니다. 프로젝트에서 아직 해야 할 작업이 있다면 작업에 대한 설명을 포함합니다. 하이라이트나 어려운 부분을 공유할 수도 있습니다
많은 정보를 쉽게 포함할 수 있으므로 가장 좋은 옵션입니다. 이렇게 하면 내가 한 작업을 명확하게 표시하고 다른 사용자가 내 기여를 사용하고 이해할 수 있기 때문에 유용합니다.
GitHub를 사용하고 모든 작업이 단일 pull 요청으로 처리된다면 이 링크를 사용할 수 있습니다.
- pull 요청 설명이 자세해야 합니다.
- 설명에 문서 시즌에 대한 작업임을 명확히 언급해야 합니다.
- Docs 시즌이 끝난 후 pull 요청에 더 많은 작업이 필요한 경우 Docs의 마지막 시즌이 이 사실을 커밋해야 합니다.
- 이 프로젝트 보고서를 제공하는 방법은 변경 로그, 커밋 목록, 검토 코멘트를 모두 한 곳에서 볼 수 있다는 이점이 있습니다.
GitHub 저장소가 Season of Docs를 사용하는 경우 작업 세부정보가 포함된 README 파일을 추가합니다.
Google Drive에 공개 폴더를 만들고 생성한 모든 패치를 포함합니다.
Google Sheets로 공개 스프레드시트를 만들고 모든 커밋을 나열합니다.
공개 Issue Tracker에서 작업 및 적절한 기타 모든 사항에 대한 명확한 참조가 포함된 단일 문제로 연결합니다. 문제는 지금까지 수행한 모든 작업을 추적합니다. 문제에 모든 커밋이 나열되어 있거나 다른 방법으로 커밋을 쉽게 찾을 수 있는지 확인하세요.
변경사항의 통합 또는 컨텍스트 차이로 연결되는 링크입니다. 다른 사람들에게 유용하도록 기술 문서 작성 프로젝트의 이름과 본인 이름이 포함된 헤더를 포함해야 합니다.
내 작업을 설명하는 잘못된 예
금지사항:
- 전체 프로젝트의 소스 코드나 작업 디렉터리를 포함하는 tarball 또는 zip 파일에 링크합니다.
- 프로젝트의 기본 소스 저장소 상단 링크 예를 들어 cpython을 사용하는 경우 이 링크(https://github.com/python/cpython)는 유용하지 않습니다.
- 프로젝트의 소스 저장소 클론의 링크를 연결합니다. 이렇게 하면 작업 내용이 다른 사용자의 저작물과 섞여서 변경사항을 파악하기가 어렵습니다.
- Season of Docs 웹사이트에 있는 프로젝트 설명의 링크를 제공합니다.
멘토용 콘텐츠
테크니컬 라이터가 적절한 프로젝트 보고서를 작성할 수 있도록 도와주세요. 테크니컬 라이터의 작업에 관한 자체 평가를 만들기 전에 이 작업을 수행하는 것이 중요합니다.
다음을 확인하세요.
- 제출물은 위에 설명된 요구사항을 충족해야 합니다.
- 제출에는 완료된 작업에 관한 설명, 충족된 요구사항, 특정 결정의 이유가 포함되어야 합니다.
문서 시즌이라는 개념은 테크니컬 라이터들이 많은 문서를 발송한다는 뜻은 아닙니다. 이러한 작업이 오픈소스 프로젝트 호스팅에 유용할 수 있어야 합니다.