이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- CERN-HSF
- 테크니컬 라이터:
- SabitaR
- 프로젝트 이름:
- Allpix Squared 문서의 구조 조정 및 간소화
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
개요 CERN-HSF의 Allpix Squared 프로젝트를 선택한 이유는 크게 두 가지입니다.
역량 구축: 이 프로젝트의 기존 문서는 포괄적이며 여러 콘텐츠 형식을 통합합니다. 이 방대한 문서 모음을 감사하고 재구성하면 정보 구조와 글쓰기 기술을 연마하는 데 도움이 될 것입니다. 게다가 프로젝트 도메인 (입자 물리학)은 처음입니다. 개발자 상호작용 스킬을 연마하는 데 어려움을 겪습니다. 필요한 배경 연구를 수행하고 적절한 질문을 하면 테크니컬 라이터가 개발자의 입력을 처리하고 모든 수준의 사용자에게 유용한 콘텐츠를 제공할 수 있다고 생각합니다. 이 프로젝트를 통해 이 이론을 테스트해 보겠습니다.
기술적 노하우: 이 프로젝트에는 학습 과제 목록의 상단에 있는 Hugo라는 도구가 필요합니다. LaTeX-Markdown-Hugo-GitLab-CI 워크플로를 배우게 되어 기쁩니다.
테크니컬 라이터 탐색 단계에서 프로젝트 멘토와 짧게 상호작용하고 기존 문서 묶음 구조를 익혔습니다. 또한 데모 웹사이트 (https://ap2-demo.netlify.app/)를 만들어 내 Windows 컴퓨터에서 Hugo와 Docsy를 올바르게 구성할 수 있는지 테스트했습니다. 웹사이트를 Netlify에 배포할 수 있었지만 Gitlab 페이지에는 배포할 수 없었습니다. 이 프로젝트에서 현재 배포 워크플로를 유지하기 위해 Hugo Docsy 테마를 Gitlab 페이지에 배포하는 방법을 찾아보겠습니다.
예상 프로젝트 결과 - 문서, 코드 참조, 튜토리얼, 뉴스를 통합하는 간소화된 프로젝트 웹사이트. - 사용자와 개발자용 콘텐츠를 구분하고 이전에 누락된 정보가 포함된 사용자 매뉴얼을 재구성 및 검토했습니다. - 사용 가능한 방법 문서, FAQ, 일반적인 문제 예시로 구성된 튜토리얼 워크플로
프로젝트 도구 Allpix Squared의 현재 문서에서는 GitLab 및 Gitlab CI 외에 LaTeX, Doxygen, pandoc, Hugo를 사용합니다. 프로젝트 멘토와 저는 MathJax 플러그인을 사용해 콘텐츠를 LaTeX에서 마크다운으로 옮기는 방법에 관해 대화를 나누었습니다. 제가 성공하면 문서 워크플로에 휴고, 마크다운, Doxygen, git, Gitlab CI가 포함됩니다. 동일한 웹사이트/플랫폼 내에서 튜토리얼을 유지하기 위해 Hugo와 Markdown을 사용할 예정입니다. 튜토리얼에 Codelabs-as-a-Tool (ClaaT)을 사용할 수 있는지 궁금합니다. 이번 7월에는 ClaaT-Hugo 워크플로를 테스트하고 멘토가 선정되면 멘토와 논의해 보고 싶습니다.
프로젝트 기간 표준 3개월 (2020년 9월 14일~2020년 11월 30일) 내에 Allpix Squared 프로젝트를 완료해 달라고 요청합니다. 이 기간 동안 주당 약 15시간을 투자할 예정입니다. 이 시간에는 필요에 따라 멘토 회의와 관련 이메일도 포함됩니다. 커뮤니티 유대감 형성 및 프로젝트 완료도 GSoD 타임라인을 지킬 것입니다.
프로젝트 과제 기존 Allpix Squared 문서 모음에 대해 제가 제안한 업데이트를 다음과 같이 구현할 것입니다. 1. 다음과 같은 옵션을 조사하고 토론하며 살펴봅니다 (2020년 8월 17일~2020년 9월 13일). - 프로젝트 요구사항 이해하기 - Allpix Squared 소프트웨어를 설치하여 현재 문서에서 누락된 정보가 있는 경우 이를 파악합니다. - 필요한 사용자 인증 정보를 요청합니다. - Allpix Squared의 다양한 사용자를 위한 사용자 워크플로 만들기 - 사용자 역할별로 콘텐츠 분류 - LaTeX 파일을 마크다운으로 변환하는 것의 영향을 확인합니다. - 소스 저장소를 통합하거나 여러 Git 저장소와 함께 작업하는 방법을 이해합니다. - 보너스: 튜토리얼을 위한 옵션으로 CLaaT를 테스트합니다. - 보너스: 커뮤니티 참조 단계를 위한 간단한 문서 작성: 커뮤니티 가이드 작성 도움말/참여자 간단한 문서 작성 지원
콘텐츠 재구성, 검토, 개선 (2020년 9월 14일~10월 19일): 주당 작업 2개, 작업당 약 5~7시간 이 타임라인에는 예상치 못한 지연이나 문제를 처리하기 위한 여유 기간이 포함됩니다.
- 사용자 워크플로를 염두에 두고 기존 콘텐츠 및 사용자 분류 검토
- 다양한 사용자를 위해 재구성된 콘텐츠 워크플로를 개괄적으로 설명하고 테스트합니다.
- 누락된 콘텐츠 소싱 및 개선
- LaTeX 파일을 마크다운으로 변환
- 사용자 가이드 및 개발자 가이드 목차를 완료합니다.
- 사용자 및 개발자 가이드의 PDF 생성
- 보너스: 예시와 문제를 토대로 한 튜토리얼 콘텐츠 구조화
- 보너스: 방법 예에 대한 튜토리얼 워크플로 설정 타임라인: 5주 (문서 개발 단계)
웹사이트 구축 (2020년 10월 19일~11월 30일): 주당 작업 1~2개, 작업당 약 5~7시간 이 타임라인에는 문제를 해결하고 최종 출력을 미세 조정하는 버퍼 주간이 포함됩니다.
- 게시 워크플로 이해 및 테스트
- Hugo 및 Docsy를 사용하여 웹사이트 구조 구축
- Docsy를 사용해 현재 자동 배포 및 워크플로를 유지하는 방법을 테스트합니다.
- Doxygen에서 콘텐츠 가져오기
- LaTex 또는 마크다운 콘텐츠로 사용자 설명서, 개발자 가이드, 튜토리얼 개발
- 프로젝트 웹사이트의 디자인과 분위기 (로고, 색상, 템플릿, 레이아웃, 링크, 사용성, Gitlab CI/CD) 마무리 일정: 6주 (문서 개발 단계)