이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- VideoLAN
- 테크니컬 라이터:
- 에디옹 애니 아식포
- 프로젝트 이름:
- VLC 사용자 문서 현대화 (재작성)
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
추상
사용자 문서는 최종 사용자가 제품 또는 서비스를 사용하는 데 도움을 주기 위해 작성되었습니다. 양질의 사용자 문서는 사용자가 소프트웨어 사용 방법, 기능, 도움말, 유용한 정보를 배우고 소프트웨어 사용 시 발생하는 일반적인 문제를 해결하는 방법을 제공하기 때문에 매우 중요합니다. 또한 지원 비용을 절감하며 제품의 기업 정체성의 일부이기도 합니다. 양질의 사용자 문서는 제품, 개발자 팀의 건전성을 보여주는 지표입니다.
양질의 사용자 문서가 없다면 사용자는 위와 같은 작업을 효과적이고 효율적으로 수행하는 방법을 알 수 없습니다. 사용자 문서는 제품의 성공을 보장하는 데 중추적인 역할을 할 수 있습니다. 훌륭한 커뮤니케이션은 항상 모든 비즈니스 또는 제품의 중심에 있고, 훌륭한 문서는 이러한 커뮤니케이션을 누구나 쉽게 사용할 수 있는 관리 가능한 프레임워크로 만들어 주기 때문에 모든 비즈니스 또는 제품의 핵심입니다.
이 글을 작성하는 시점을 기준으로 VLC 사용자 문서는 4,634,065회 액세스되었고 VLC 미디어 플레이어는 기본 웹사이트에서 매월 약 2,300만 회 다운로드되었습니다. 이는 전 세계 많은 사람들이 VLC 미디어 플레이어를 사용하고 있으며 미디어 플레이어 사용 방법에 대한 안내를 보려면 사용자 문서를 읽어 보길 원한다는 것을 알 수 있습니다. 하지만 VLC 미디어 플레이어 사용자 문서는 현재 오래되고 불완전하며 (2015년 10월 28일에 마지막으로 수정됨) VideoLAN 커뮤니티는 이 프로젝트를 통해 사용자 문서를 개선하여 최종 사용자가 VLC 미디어 플레이어를 사용할 때 원활한 환경을 제공할 수 있기를 바랍니다.
현재 상태
현재 위키 페이지에서 사용자 설명서를 제공합니다. 더 이상 사용되지 않으며, 불완전하거나, 탐색하거나, 정보를 찾기 어려우며, 미디어 플레이어의 현재 버전에 관한 정보를 다루지 않으며, 독일어로만 번역되어 영어를 읽을 수 없는 사람들에게 큰 좌절을 야기합니다.
제안된 사용자 문서를 현재 문서보다 개선할 수 있는 이유는 무엇인가요?
제안된 사용자 문서는 개선을 통해 효율성, 일관성, 최종 사용자가 안심할 수 있도록 구성되어 있습니다. 문서에는 가이드와 관련 이미지가 포함되어 있으며, VLC 미디어 플레이어의 각 기능을 사용하는 방법에 대한 안내와 설명도 포함되어 있으며, 최신 상태이고, 탐색하기 쉽고, 이해하기 쉬우며, 5개 이상의 주요 언어로 번역할 수 있습니다.
멘토: 장바티스트, 알렉스, 사이먼
분석
Jean-Baptiste와 저는 개선을 위해 현재 사용자 문서를 이전할 새로운 환경에 대해 대화를 나누었습니다. 그는 Sphinx로 작성된 소스 파일의 Gitlab 저장소와 Read the Docs에 호스팅된 기본 문서를 보여주는 두 개의 링크를 공유했고, 새로운 문서가 이와 비슷할 것이라고 말했습니다. 이 도구의 작동 방식을 더 잘 이해하기 위해 이러한 도구에 대해 많이 조사했습니다.
스핑크스
Sphinx는 소프트웨어 문서를 위한 강력하고 성숙한 솔루션입니다. 여기에는 단일 소스 게시, 포함을 통한 콘텐츠 재사용, 콘텐츠 유형과 태그를 기반으로 한 조건부 포함, 모바일 및 데스크톱에서 뛰어난 사용자 환경을 제공하는 여러 성인용 HTML 테마, 페이지, 문서, 프로젝트 전반의 참조, 색인 및 용어집 지원 및 국제화 지원 등 작성자가 기대하는 여러 기능이 포함됩니다. 또한 reStructuredText를 마크업 언어로 사용하며, reStructuredText의 강력한 기능과 단순성, 문서를 번역할 수 있다는 장점이 많습니다.
문서 읽기
문서를 읽으면 문서 빌드, 버전 관리, 호스팅을 자동화하여 소프트웨어 문서를 단순화할 수 있습니다. 항상 동기화 상태를 유지합니다. 즉, Git, Mercurial, Bazaar, Subversion과 같이 자주 사용하는 버전 제어 시스템에 코드를 푸시할 때마다 Read the Docs가 자동으로 문서를 빌드하므로 코드와 문서를 항상 최신 상태로 유지할 수 있습니다. 여러 버전이 있습니다. Docs 읽기는 여러 버전의 문서를 호스팅하고 빌드할 수 있으므로 버전 제어 시스템에 별도의 브랜치 또는 태그를 갖는 것만큼이나 문서의 1.0 버전과 2.0 버전의 문서를 쉽게 사용할 수 있습니다. Read the Docs는 무료 오픈소스이며 거의 모든 인간 및 컴퓨터 언어로 된 약 10만 개의 대규모 및 소규모 오픈소스 프로젝트에 대한 문서를 호스팅합니다.
평가
Sphinx는 매우 강력한 도구이며, Read the Docs는 다양한 버전에 걸쳐 문서를 최신 상태로 유지하는 Sphinx 문서 호스팅을 제공합니다. 함께 사용하면 개발자와 테크니컬 라이터가 최종 사용자에게 가장 적합한 사용자 문서를 만드는 데 사용할 수 있는 멋진 도구 모음입니다.
Sphinx에서는 문서를 여러 언어로 번역할 수 있도록 지원합니다. 문서 관리에 사용될 버전 제어를 지원합니다. 누구나 수정할 수 있고 올바른 정보를 추가할 수 없는 현재의 위키와 달리, 이 버전 제어 시스템은 모든 변경사항을 먼저 검토한 후에 기본 저장소에 병합합니다. 또한 버전 제어를 통해 문서에 대한 오픈소스 기여도가 높아집니다. 사용자가 문제를 작성하고 공개 pull 요청 등을 할 수 있기 때문입니다. Sphinx와 문서 읽기는 ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs 등과 같은 다른 훌륭한 커뮤니티 목록에서 사용되며 새로운 VLC 사용자 문서에 사용할 수 있는 훌륭한 도구입니다.
이러한 도구에 관해서 이야기한 것이 아니라 기본적인 샘플도 만들었습니다. 이 링크는 제 Gitlab 저장소 링크(https://gitlab.com/Didicodes/demo-vlc-user-documentation)이며 readthedocs의 호스팅된 버전은 [https://vlc-user-document-demo.readthedocs.io/en/latest/](https://vlc-user-document-demo.readthedocs.io/en/latest/)에서 확인할 수 있습니다.
제안된 문서의 구조
VLC 사용자 문서(https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing)의 구조를 만들었습니다. 새로운 구조의 구현을 시작하려면 먼저 멘토의 승인을 받아야 합니다. 따라서 멘토가 검토한 후에 구조가 변경될 수 있습니다.
프로젝트 목표
- 문서를 재구성합니다.
- VLC의 최신 버전에 맞게 문서를 업데이트합니다.
- Sphinx 및 ReadtheDocs를 사용하여 사용자 문서를 Gitlab으로 이전합니다.
- 사용하지 않는 이미지와 정보를 삭제합니다.
- 이해하기 쉽도록 사용자 문서를 다시 작성합니다.
- Sphinx 국제화를 사용하여 번역하도록 설정합니다.
- 사용자가 문서를 읽는 동안 발생한 문제를 보고하거나 해결할 수 있도록 문서 커뮤니티를 기반으로 합니다.
이 프로젝트가 필요한 이유
저는 여러분이 글을 통해 다른 사람에게 깨달을 수 있을 때 코드 작성, 문제 해결, 소프트웨어 빌드가 잠재력을 최대한 발휘할 수 있다는 확신을 가지고 있었습니다. 개인적으로 저는 멀티미디어용 무료 소프트웨어 솔루션을 개발하기 위해 VideoLAN 커뮤니티에서 벌인 노력에 항상 매료되어 왔습니다. 어릴 때부터 VLC 미디어 플레이어는 음악을 듣거나 영화를 볼 때 항상 사용했던 소프트웨어였습니다. 소리가 매우 크고 여러 기능으로 구성되어 있기 때문입니다. 제가 어린 시절을 훌륭하게 만드는 데 기여한 커뮤니티와 함께 일하는 것은 영광입니다.
내가 이 프로젝트에 적합한 담당자인 이유
다음과 같은 이유로 이 프로젝트에 적합한 업무 담당자라고 생각합니다.
- 이전에 조직 문서를 개선한 경험이 있고 모든 버전 제어 시스템을 사용할 수 있으므로 Gitab에서 명령을 실행하는 것은 문제가 되지 않습니다. 또한 사람들을 위한 가치를 창출하는 프로젝트를 하게 되는 원동력이 되어줍니다.
- 누군가가 가능한 가장 효율적인 방법으로 무언가를 하기를 원한다면 그것을 문서화한다고 생각합니다. 프로세스를 문서화하면 효율성, 일관성, 그리고 관련된 모든 사람에게 안심할 수 있습니다.
- VLC 사용자의 필요를 잘 알고 있습니다. 저도 그 중 한 명이기 때문입니다. 이렇게 하면 전 세계의 다른 모든 사용자가 한눈에 이해할 수 있는 방식으로 문서를 작성할 수 있습니다.