이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- VLC
- 기술 문서 작성자:
- 아비셱 프라탑 싱
- 프로젝트 이름:
- VLC 사용자 문서 현대화 계속
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
문서의 현재 상태
VLC 사용자 문서가 현대화되고 업데이트되고 있습니다. 위키 기반의 이전 문서[1] 에서 ReadTheDocs에 호스팅되는 최신 사용자 문서[2] 로 전환하는 작업이 진행 중입니다.
타겟 잠재고객
대상 사용자는 일반 미디어 플레이어 외에도 VLC 미디어 플레이어의 기능을 살펴보고 싶은 호기심 많은 사용자이며, 어느 정도는 개발자에게도 간편한 참조 가이드 역할을 할 것입니다. 따라서 최종 사용자가 자유롭게 선택할 수 있도록 GUI 기반 안내 (해당하는 경우 이미지 포함)와 CLI 기반 메서드 (코드 스니펫 포함)를 모두 포함할 계획입니다.
문서 (특히 GUI 섹션)의 언어는 컴퓨터 운영에 대한 지식이 거의 없는 사람이 가이드를 이해하고 구현할 수 있을 만큼 완화되어야 한다고 생각합니다. 반면에, 코더가 흥미를 잃는다고 해서 너무 길거나 설명이 필요하면 안 됩니다 (특히 CLI 섹션).
페이지 시작 부분에 기본 요건을 언급하거나 잘 알고 있는 사용자가 건너뛸 수 있는 선택적 섹션을 유지하여 적절한 균형을 유지할 수 있습니다.
번역을 빌드할 때 타겟층은 영어와 번역할 언어를 잘 이해하는 VLC 개발자/사용자입니다.
도구
새 문서는 Sphinx로 빌드되고 ReadTheDocs에서 호스팅되며 버전 관리 시스템은 GitLab에 구현됩니다. 이전에 Git과 GitHub을 사용해 본 경험이 있어 GitLab을 이해하는 데 도움이 되었습니다. 다만 GitLab에는 특정 기능이 몇 가지 있어 익히는 데 시간이 걸렸습니다.
Sphinx의 경우 오픈소스 애호가의 말을 통해 문서를 빌드하는 데 Sphinx를 사용하는 조직이 얼마나 많은지 알게 되었습니다. 특히 Sphinx를 사용하여 사용자 설명서[3] 및 API 문서[4]를 빌드하는 Blender가 대표적인 예입니다.
버전 관리 및 기술 문서 호스팅에 유용한 도구인 ReadTheDocs에 약간 익숙했습니다. 따라서 큰 문제 없이 VLC 문서를 빌드할 수 있었고 사용된 형식인 reStructured Text에 익숙합니다.
VLC는 번역을 위해 Babel을 사용하여 i18n 및 l10n을 구현하기 위해 .po 파일을 생성합니다. 현재 Babel 워크플로와 Sphinx를 사용하여 .mo 파일을 빌드하는 방법을 익히고 있습니다.
이 기간 동안 위에 언급된 도구의 복잡한 기능을 더욱 익히고자 합니다.
배송물 및 주간 일정
2019년 프로젝트의 일환으로 설치, 인터페이스, 오디오, 동영상, 재생 등의 일부(대부분의 기본 기능)가 이미 다루어졌습니다. 따라서 2020년 프로젝트에서는 사용자 문서의 고급 사용 섹션을 업데이트하고 작업하고자 합니다.
결과물 1 [1~2주]: #7[5]에 언급된 대로 Transcode 문서를 업데이트합니다.
- 트랜스코드
- 여러 동영상 트랜스코딩
- 로고를 추가하세요.
- 동영상 병합
- 오디오 추출 및 파일에서 오디오 추출
- DVD 리핑
결과물 2 [3~4주]: Firefox 77, Chrome 83, Edge 83에서 테스트하는 동안 VLC를 웹 플러그인으로 사용[6] 업데이트
- 동영상을 사용하여 웹페이지 만들기
- 삽입 태그 속성
- JavaScript API 설명
결과물 3 [5주차]: 명령줄 인터페이스[7] 명령어를 테스트하고 적절하게 업데이트합니다.
- 스트림
- 모듈 선택
- 항목별 옵션
- 필터
6주 차: 위의 세 가지 결과물에 대한 버퍼 주
결과물 4 [7~8주]: 번역 준비 업데이트 외에도 다른 언어로 번역할 준비를 하겠습니다. 이는 번역 후 영어를 사용하지 않는 사용자가 문서를 읽을 수 있기 때문에 중요합니다. 참고로 VLC는 세계 지배[8]에 한 걸음 더 다가가게 됩니다.
제안서의 도구 섹션에서 언급했듯이 현재 VLC는 Babel을 사용하여 번역을 위한 .po 파일을 생성합니다. 사용자/자원봉사자가 다음을 수행하는 절차를 문서화합니다.
- 기본 문서를 다운로드하여 로컬로 빌드합니다.
- Babel을 사용하여 필요한 파일을 생성합니다.
- 문자열의 번역을 입력합니다.
- Sphinx를 사용하여 번역된 문서를 빌드합니다.
- 변경사항을 커밋합니다.
배포 5[9~10주 차]: 모듈 문서 준비 멘토와 논의한 바와 같이 모듈 문서는 두 부분으로 준비할 계획입니다.
파트 - I: 코드베이스에서 유효한 옵션을 찾아 해당 위키 페이지에서 한 줄로 된 사용 (및 기본값)을 추출하는 스크립트를 통해 모듈 근처에 파일을 만듭니다. 이 내용은 기본 초안으로 사용됩니다.
II단계: 특정 플랫폼 (Windows, 시간이 허락하는 경우 Fedora)의 모든 모듈, 플러그인, 옵션을 연결하는 플랫폼별 구조를 빌드합니다.
모듈 근처에 파일을 만들면 문서가 소스 코드와 가까워집니다. 하단 위로 접근 방식을 사용하면 기본 모듈 문서는 1부에서 만든 파일을 결합하고 2부에서 만든 구조를 참조로 사용하여 빌드됩니다.
자동화를 통해 생성된 파일은 검토가 필요하지만 우선적으로 작동하는 프레임워크를 만드는 것이 중요합니다. 완료되면 가능한 시간 내에 파일을 검토하여 옵션을 확인합니다. 이 프레임워크는 개발자와 유지보수자가 관련 사용 사례를 추가하여 기여할 수 있게 되면 우선순위가 높아집니다.
보너스 결과물[11주차]: 4.0 출시 준비 프로젝트가 예정대로 진행될 경우를 대비해 보너스 결과물을 제안하고자 합니다. 멘토와 논의한 바와 같이 4.0 출시를 준비하려면 버전 3.0에 관한 안정적이고 거의 완성된 문서가 있어야 합니다.
따라서 다음 섹션의 이미 완료된 문서를 검토하여 언급된 메서드를 확인하고 업데이트하겠습니다.
- 기본 사용: 미디어, 재생, 오디오, 동영상, 자막, 핫키, 녹화 파일, 설정, 도움말 및 도움말
- 고급 사용 사례: 플레이어, 인터페이스, 트랜스코딩, 스트리밍, 비정상적인 사례
- 부가기능: 확장 프로그램, 스킨
12주 차: 위 세 가지 산출물에 대한 완충 주 + 최종 보고서.
이 프로젝트에 적합한 이유는 무엇인가요?
저는 기술 애호가로서 소프트웨어를 사용/테스트하고 때로는 코드베이스를 이해하려고 시도한 경험이 있습니다. 사실 오픈소스 조직의 코드베이스를 이해하려고 시도하면서 문서의 중요성을 처음으로 진정으로 깨달았습니다. 또한 음악 애호가로서 VLC를 조정하는 데 많은 경험이 있습니다. :)
그 외에는 평생 연구원과 작가로 활동했습니다. 무언가를 적어두지 않으면 제대로 이해하지 못하는 편이라 이 습관 덕분에 효율적으로 메모하고 문서화하는 데 능숙해졌습니다.
이 두 가지 습관이 교차하는 점이 저는 기술 문서에 잘 어울립니다. 사용자가 이해할 수 있는 방식으로 조사 결과/절차를 문서화하면서 기술적인 측면을 살피는 방법을 찾을 수 있습니다.
링크: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/ko/latest/index.html [3] https://docs.blender.org/manual/ko/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35