이 페이지에는 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, Alex, Simon
분석
Jean-Baptiste와 저는 개선을 위해 현재 사용자 문서를 이전할 새로운 환경에 대해 대화를 나누었습니다. 그는 Sphinx로 작성된 소스 파일의 Gitlab 저장소와 Read the Docs에 호스팅된 기본 문서를 보여주는 두 개의 링크를 공유했으며 새 문서도 이와 비슷할 것이라고 말했습니다. 작동 방식을 더 잘 이해하기 위해 이러한 도구에 대해 많이 조사했습니다.
스핑크스
Sphinx는 소프트웨어 문서를 위한 강력하고 성숙한 솔루션입니다. 여기에는 작성자가 기대하는 여러 기능이 포함됩니다. 또한 reStructuredText를 마크업 언어로 사용하며, 많은 강점은 reStructuredText의 강력한 기능과 직관적이고 문서를 번역할 수 있다는 것입니다.
문서 읽기
문서를 읽으면 문서 빌드, 버전 관리, 호스팅을 자동화하여 소프트웨어 문서를 단순화할 수 있습니다. 항상 동기화 상태가 유지됩니다. 즉, Git, Mercurial, Bazaar 또는 Subversion과 같은 선호하는 버전 제어 시스템에 코드를 푸시할 때마다 Read the Docs가 자동으로 문서를 빌드하므로 코드와 문서를 항상 최신 상태로 유지할 수 있습니다. 여러 버전이 있습니다. Read the Docs는 여러 버전의 문서를 호스팅하고 빌드할 수 있으므로 1.0 버전의 문서와 2.0 버전의 문서를 버전 제어 시스템에 별도의 브랜치나 태그를 갖는 것만큼이나 간단하게 사용할 수 있습니다. 이 문서는 무료 오픈소스이며 거의 모든 인간 및 컴퓨터 언어로 된 거의 100,000개의 대규모 및 소규모 오픈소스 프로젝트에 대한 문서를 호스팅합니다.
평결
Sphinx는 놀라울 정도로 강력한 도구이며, Read the Docs는 Sphinx 문서를 호스팅하므로 여러 버전에서 문서를 최신 상태로 유지합니다. 이러한 도구는 개발자와 테크니컬 라이터가 최종 사용자에게 가장 적합한 사용자 문서를 작성하는 데 사용할 수 있는 멋진 도구 모음입니다.
Sphinx에는 문서를 여러 언어로 번역할 수 있는 기능이 포함되어 있습니다. 문서 관리에 사용될 버전 제어를 지원합니다. 누구나 편집할 수 있고 올바른 정보를 추가할 수 없는 현재의 위키와 달리, 이 버전 제어 시스템은 모든 변경 사항을 기본 저장소에 병합하기 전에 먼저 검토합니다. 또한 버전 제어를 통해 문서가 프로젝트에 대한 오픈소스 기여를 늘릴 수 있습니다. 사용자가 문제를 만들고, 열린 pull 요청 등을 할 수 있기 때문입니다. Sphinx와 Docs는 ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs 등과 같은 훌륭한 커뮤니티 목록에서 사용되며 새로운 VLC 사용자 문서에 사용할 수 있는 훌륭한 도구입니다.
이러한 도구에 관해서 읽은 것이 아니라 기본적인 샘플도 만들었습니다. 이 링크는 내 Gitlab 저장소에 대한 링크(https://gitlab.com/Didicodes/demo-vlc-user-documentation)이며, readthedocs에 호스팅된 버전은 [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-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 사용자의 필요를 잘 알고 있습니다. 이렇게 하면 전 세계의 다른 사용자가 바로 이해할 수 있는 방식으로 문서를 작성할 수 있습니다.