이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- CERN-HSF
- 기술 문서 작성자:
- SabitaR
- 프로젝트 이름:
- Allpix Squared 문서 재구성 및 간소화
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
개요 저는 두 가지 큰 이유 때문에 CERN-HSF의 Allpix Squared 프로젝트를 선택했습니다.
역량 함양: 이 프로젝트의 기존 문서는 포괄적이며 여러 콘텐츠 형식을 통합합니다. 이 방대한 문서 모음을 감사하고 재구성하면 정보 아키텍처와 작성 기술을 다듬는 데 도움이 됩니다. 또한 프로젝트 도메인 (입자 물리학)이 저에게는 생소합니다. 개발자와의 상호작용 기술을 연마할 수 있습니다. 필요한 배경 조사를 수행하고 적절한 질문을 하면 테크니컬 라이터가 개발자의 입력을 처리하고 모든 수준의 사용자에게 유용한 콘텐츠를 제공할 수 있다고 생각합니다. 이 프로젝트를 통해 이 이론을 테스트할 수 있습니다.
기술적 노하우: 이 프로젝트에는 학습 목록 상단에 있는 도구인 Hugo가 필요합니다. LaTeX-Markdown-Hugo-GitLab-CI 워크플로를 배우게 되기를 기대합니다.
기술 문서 작성자 탐색 단계에서 프로젝트 멘토와 잠시 상호작용하고 기존 문서 모음 구조를 숙지했습니다. 또한 Windows 머신에서 Hugo와 Docsy를 올바르게 구성할 수 있는지 테스트하기 위해 데모 웹사이트 (https://ap2-demo.netlify.app/)를 빌드했습니다. 웹사이트를 Netlify에는 배포할 수 있었지만 Gitlab Pages에는 배포할 수 없습니다. 이 프로젝트에서 현재 배포 워크플로를 유지하려면 Hugo Docsy 테마를 Gitlab Pages에 배포하는 방법을 찾아야 합니다.
예상 프로젝트 결과 - 문서, 코드 참조, 가이드, 뉴스를 통합하는 간소화된 프로젝트 웹사이트입니다. - 사용자와 개발자를 위한 콘텐츠를 구분하고 이전에 누락된 정보를 포함하도록 재구성 및 검토된 사용자 설명서 - 튜토리얼 워크플로: 사용 가능한 방법 문서, FAQ, 자주 발생하는 문제의 예시
프로젝트 도구 Allpix Squared의 현재 문서는 GitLab 및 Gitlab CI 외에도 LaTeX, Doxygen, pandoc, Hugo를 사용합니다. 프로젝트 멘토와 저는 MathJax 플러그인을 사용하여 LaTeX에서 Markdown으로 콘텐츠를 이전할 수 있는지 논의했습니다. 성공하면 문서 워크플로에 Hugo, Markdown, Doxygen, git, Gitlab CI가 포함됩니다. 튜토리얼을 동일한 웹사이트/플랫폼에 유지하기 위해 Hugo와 마크다운을 사용하겠습니다. 튜토리얼에 Codelab-as-a-Tool (ClaaT)을 사용할 수 있는지 궁금합니다. 이번 7월에 ClaaT-Hugo 워크플로를 테스트하고 선발된 경우 멘토와 논의하고자 합니다.
프로젝트 기간 주당 약 15시간을 표준 3개월 (2020년 9월 14일~2020년 11월 30일) 내에 Allpix Squared 프로젝트를 완료할 계획입니다. 이 시간에는 필요에 따라 멘토 미팅과 관련 이메일이 포함됩니다. 커뮤니티 유대감 형성 및 프로젝트 확정을 위한 GSoD 타임라인도 준수합니다.
프로젝트 작업 기존 Allpix Squared 문서 모음에 제안된 업데이트를 구현하려는 방법은 다음과 같습니다. 1. 옵션을 조사, 토론, 탐색 (2020년 8월 17일~9월 13일): - 프로젝트 요구사항 이해 - Allpix Squared 소프트웨어를 설치하여 현재 문서에서 누락된 정보가 있는지 확인합니다. - 필요한 사용자 인증 정보를 요청합니다. - Allpix Squared의 다양한 사용자를 위한 사용자 워크플로 만들기 - 사용자 역할별로 콘텐츠 분류하기 - LaTeX 파일을 Markdown으로 변환할 때의 의미 확인하기 - 소스 저장소 통합 또는 여러 git 저장소 작업 방법 이해하기 - 보너스: 튜토리얼 옵션으로 CLaaT 테스트하기 - 보너스: 참여자가 문서를 유지하는 데 도움이 되는 빠른 스타일 가이드/쇼트코드 참조 작성하기 타임라인: 커뮤니티 결속 단계
콘텐츠 구조 조정, 검토, 개선 (2020년 9월 14일~2020년 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주 (문서 개발 단계)