이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- VLC
- 테크니컬 라이터:
- 아비셱 프라탑 싱
- 프로젝트 이름:
- VLC 사용자 현대화 문서 계속하기
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
문서의 현재 상태
VLC 사용자 문서를 현대화하고 업데이트하는 중입니다. 위키 기반의 이전 문서[1] 에서 ReadTheDocs에 호스팅된 Sphinx의 최신 사용자 문서[2] 로 전환하는 작업이 진행 중입니다.
타겟 잠재고객
타겟 고객은 일반 미디어 플레이어보다 VLC 미디어 플레이어의 기능을 더 자세히 알아보려는 호기심 많은 사용자이며, 어느 정도는 쉬운 참조 가이드로 제공되어 개발자에게도 도움이 될 것입니다. 따라서 최종 사용자가 자유롭게 선택할 수 있도록 GUI 기반 명령 (관련 있는 이미지 포함)과 CLI 기반 방법 (코드 스니펫 포함)을 모두 포함할 계획입니다.
문서 언어 (특히 GUI 섹션)는 컴퓨터를 실제로 사용한 경험이 있는 사람도 이 가이드를 이해하고 구현할 수 있을 만큼 약화되어야 한다고 생각합니다. 반면에 코더가 관심을 잃을 정도로 길거나 설명이 필요해지면 안 됩니다 (특히 CLI 섹션).
페이지 시작 부분에 기본 요건을 언급하거나 초보자도 건너뛸 수 있는 선택 섹션을 마련하면 적절한 균형을 유지할 수 있습니다.
번역 작성의 경우 타겟 대상은 영어와 번역 대상 언어를 잘 이해하고 있는 VLC 개발자/사용자입니다.
도구
새로운 문서는 Sphinx로 빌드되고 ReadTheDocs에 호스팅되며 버전 제어 시스템은 GitLab에서 구현됩니다. 과거에 Git과 GitHub를 사용해 본 경험이 있었고, 여러 가지 기능을 배우는 데 시간이 걸렸는데도 이를 통해 GitLab을 익힐 수 있었습니다.
Sphinx에 관해서는 동료 오픈소스 애호가가 문서 작성에 Sphinx를 사용하는 조직이 얼마나 되는지 언급하면서 이에 대해 읽었습니다 (예: Blender는 사용자 설명서[3] 및 API 문서[4] 작성에 Sphinx를 사용함).
저는 버전 관리와 기술 문서 호스팅에 적합한 ReadTheDocs에 대해 약간 알고 있었습니다. 따라서 큰 문제 없이 VLC 문서를 빌드할 수 있었고 사용되는 형식인 reStructured Text에 익숙했습니다.
번역을 위해 VLC는 i18n 및 l10n을 구현하기 위해 Babel을 사용하여 .po 파일을 생성합니다. 현재 Babel 워크플로와 Sphinx를 사용하여 .mo 파일을 빌드하는 방법을 숙지하고 있습니다.
결합 기간을 사용하여 위에서 언급한 도구의 복잡성을 더 잘 숙지하려고 합니다.
배송물 및 주간 일정
2019 프로젝트의 일환으로 설치, 인터페이스, 오디오, 동영상, 재생 등(대부분의 기본 기능)은 이미 다뤘습니다. 따라서 2020년 프로젝트에서 사용자 문서의 고급 사용 섹션을 업데이트하고 관련 작업을 진행하고자 합니다.
DELIVERABLE 1 [1-2주 차]: #7[5]에 언급된 트랜스코드 문서를 업데이트합니다.
- 트랜스코딩
- 여러 동영상 트랜스코딩
- 로고를 추가하세요.
- 동영상 병합
- 오디오 추출 및 파일에서 오디오 추출
- 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주 차: 위의 3개 결과물에 대한 여유 주 + 최종 보고서
이 프로젝트에 적합한 담당자인 이유는 무엇인가요?
기술 애호가로서 소프트웨어 사용/테스트 경험이 있으며 코드베이스를 이해하려고 노력하는 경우도 있습니다. 실제로 오픈 소스 조직의 코드베이스를 이해하려고 노력하면서 문서의 중요성을 처음으로 깨달았습니다. 게다가 음악 애호가로서 저는 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/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://docs.blender.org/api/current/index.html [5] https://docs.blender.org/api/current/index.html [5]