이 페이지에는 Google Season of Docs에서 수락된 기술 작문 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- 콜리브리
- 테크니컬 라이터:
- StephDix
- 프로젝트 이름:
- Kolibri 생태계 문서 스타일 및 Workflows 규칙
- 프로젝트 기간:
- 장기 실행 (5개월)
Project description
요약
이 문서에서는 Kolibri 생태계 프로젝트에 관한 Learning Equality의 문서화된 정보에 스타일 가이드라인 및 워크플로 관리를 구현하는 방법을 자세히 설명합니다.
개요
제 제안은 네 단계로 이루어져 있습니다. 첫 번째 단계에서는 소프트웨어 개발의 LE 개념 및 스타일 가이드라인에 따른 접근성 가이드라인, 글쓰기, 형식 권장사항을 포함하여 LE 문서 스타일 가이드를 완료합니다. 두 번째 단계에서는 ReadTheDocs 및 GoogleDocs 문서에 대한 품질 감사를 수행합니다. 감사 계획에는 스타일 가이드라인 준수를 평가하기 위해 체크리스트 사용을 통합합니다. 이러한 체크리스트는 발견 항목을 기록하고 문서에 변경사항을 적용하는 데 도움이 됩니다. 세 번째 단계에서는 ReadTheDocs 및 GoogleDocs 문서의 템플릿 구조, 모양, 느낌을 작업합니다. 향후 구현 시 재사용할 수 있도록 기본 문서 유형의 각 템플릿 카테고리를 식별하는 템플릿 및 이미지 저장소를 Google Drive에 만듭니다. pull 요청 검토에서 쉽게 식별할 수 있도록 문서 문제를 제출하는 템플릿을 만들어 이 작업을 보완합니다. 마지막으로, 각 공동작업자 그룹을 위한 유용한 리소스를 그룹화하여 정보에 액세스하는 경험을 향상시키는 재능기부자 가이드를 만들겠습니다.
목적 및 범위
이 구현 계획의 목적은 Kolibri의 문서를 사용하여 최종 사용자의 경험을 개선하고 팀원과 기여자가 더 나은 문서를 작성하고 커뮤니티에서 활발히 협업할 수 있도록 지원하는 것입니다. 이 구현은 ReadTheDocs 및 Kolibri 생태계 내 Google Docs 문서의 하위 집합에 적용됩니다.
대상
구현자, 관리자 및 최종 사용자로 구성된 주요 대상은 Kolibri 문서의 가장 중요한 소비자입니다. Kolibri 문서 제작 및 사용을 위한 팀 구성원 및 공동작업자의 보조 대상.
목표
Kolibri Ecosystem Documentation의 스타일 가이드 및 워크플로 시스템은 사용자에게 기대하는 사항: 접근 가능한 언어와 일관된 레이아웃으로 이해하기 쉬운 문서를 작성합니다. 문서화 시 품질 관행을 유지합니다. 문서 채널 간에 정보에 쉽게 액세스할 수 있습니다. Kolibri 오픈소스 커뮤니티에서 협업 이니셔티브를 강화합니다.
정보 출처
정보의 출처는 Kolibri, Kolibri Studio, Kolibri Development RTD 문서, Google Drive의 Kolibri Toolkits입니다.
멋진 Radina Matic은 워밍업 활동과 프로젝트별 활동을 제공하는 데 큰 도움이 되었습니다. 조직에서 '가이드라인'과 '가이드'로 개념화한 개념에 대한 그녀의 의견과 도움을 주신 분들을 위한 가이드의 존재는 제가 아이디어를 정리하고 결론을 도출하는 데 도움이 되었습니다.
소프트웨어
Google Docs로 스타일 가이드 초안을 개발하겠습니다. 이 문서 플랫폼은 게시 준비가 된 동안 반복하기에 적합합니다. 품질 보증 감사를 위해 Google Forms를 사용하여 문서를 실시하고 평가합니다. 스프레드시트에는 문서 제어를 위해 양식 응답이 저장됩니다. GitHub를 사용하여 RTD 문서를 리팩터링하겠습니다. Git, Gitkraken, GitHub, Gitlab과 함께 작업했습니다. 마크다운과 ReStructuredText에 관한 실무 지식이 있습니다. 문법 학습을 계속할 수 있도록 문서 수정 작업에 참여할 계획입니다. 이미지와 GIF에는 Sharex를 사용하겠습니다. 다양한 출력 형식으로 렌더링되기 때문에 이 도구가 마음에 듭니다. 다이어그램과 이미지 에디션에 다이어그램을 사용하겠습니다. Diagrams 소프트웨어는 GoogleDocs, Google Drive, LibreOffice와 완벽하게 통합됩니다. 문서화 현황 탐색 단계에서 Kolibri의 문서 대부분을 수정했습니다. 대부분의 프로젝트 문서에서 문법적 오류, 오타, 레이아웃, 서체, 이미지 사용의 불일치를 발견했으며 문서 경로를 혼란스럽게 했습니다. 예를 들어 Kolibri의 사용자 가이드에서 문제 해결 섹션은 주제가 아닌 하위 주제입니다. 이 정보는 최종 사용자가 목차에서 액세스할 수 있을 만큼 매우 중요합니다. 또는 검색창과 목차 트리를 사용하여 다른 주제를 펼치고 문제 해결 도움말을 찾을 수도 있습니다.
'문제 해결' 섹션에 액세스하려면 해당 항목을 검색하거나 'Kolibri 관리'를 펼쳐 문제 해결이 문서의 일부로 포함되어 있음을 확인해야 합니다. 가이드와 가이드라인 이 프로젝트 제안서에서는 LE Kolibri 사용자 문서 스타일 가이드와 저전력 번역 가이드라인이라는 두 가지 문서를 분석했습니다. LE Kolibri 가이드에서는 제가 제안한 주제 개요와 문서화 계획과 더불어 가이드에서 개선이 필요한 몇 가지 사항을 바탕으로 추천과 의견을 작성했습니다. 저전력 번역 가이드라인의 경우 스타일 가이드의 권장사항과 기존 규칙에 따라 형식과 스타일을 변경했습니다. 분석 과정에서 가장 주목한 것은 가이드와 가이드라인으로 분류된 문서 사이에 존재하는 오해였습니다.
성과
품질보증 감사 작업에서 보다 자세히 설명하는 예비 양식을 사용하여 제안과 의견 외에 LE 번역 가이드의 품질을 검사했습니다. 다음은 평가를 통해 얻은 최종 의견입니다. ICU 구문 .js 웹사이트의 깨진 링크 가이드라인을 만드는 데 사용된 형식이 잘못되었습니다. 이 문서는 가이드라인이 아닌 가이드입니다. 서체가 일관되지 않습니다. 잘못된 제목 및 제목 사용, 부적절한 언어 사용, 축약형의 오용 대체 텍스트의 부적절한 사용. 반복되는 문장/ 명령.
두 문서의 발견 항목은 이 제안서의 결과물에 포함됩니다.
프로젝트별 작업
- LE 사용자 문서 스타일 가이드 권장사항 (댓글)
- 새로운 스타일과 형식의 저전력 번역 가이드라인
- 주제 개요
- 프로젝트 일정
- 문서 작업