이 페이지에는 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개 주요 언어로 번역할 수 있습니다.
멘토: 장 바티스트, 알렉스, 사이먼
분석
장바티스트님과 저는 현재 사용자 문서가 개선을 위해 이전될 새 환경에 관해 대화를 나눴습니다. 장바티스트님은 Sphinx로 작성된 소스 파일의 Gitlab 저장소와 Read the Docs에 호스팅된 기본 문서를 보여주는 두 개의 링크를 공유했으며 새 문서가 이와 유사할 것으로 예상한다고 말했습니다. 작동 방식을 더 잘 이해하기 위해 이러한 도구에 대해 많이 조사했습니다.
스핑크스
Sphinx는 소프트웨어 문서를 위한 강력하고 성숙한 솔루션입니다. 단일 소스 게시, 포함을 통한 콘텐츠 재사용, 콘텐츠 유형 및 태그를 기반으로 한 조건부 포함, 모바일 및 데스크톱에서 우수한 사용자 환경을 제공하는 여러 성숙한 HTML 테마, 페이지, 문서, 프로젝트 전반에서의 참조, 색인 및 용어집 지원, 다국어 지원 등 작성자가 기대하는 다양한 기능이 포함되어 있습니다. 또한 reStructuredText를 마크업 언어로 사용하며, reStructuredText의 강력하고 직관적인 기능과 문서를 번역할 수 있는 기능에서 많은 강점이 비롯됩니다.
문서 읽기
Read the Docs는 문서 빌드, 버전 관리, 호스팅을 자동화하여 소프트웨어 문서를 간소화합니다. 동기화 중단이 발생하지 않습니다. 즉, Git, Mercurial, Bazaar, Subversion 등 좋아하는 버전 제어 시스템에 코드를 푸시할 때마다 Read the Docs에서 자동으로 문서를 빌드하므로 코드와 문서가 항상 최신 상태로 유지됩니다. 여러 버전이 있습니다. Read the Docs는 여러 버전의 문서를 호스팅하고 빌드할 수 있으므로 버전 관리 시스템에 별도의 브랜치나 태그를 사용하는 것처럼 간편하게 문서의 1.0 버전과 2.0 버전을 사용할 수 있습니다. Read the Docs는 무료 오픈소스이며 거의 모든 인간 및 컴퓨터 언어로 작성된 크고 작은 오픈소스 프로젝트의 문서를 거의 100,000개 호스팅합니다.
평결
Sphinx는 놀라울 정도로 강력한 도구입니다. Sphinx의 'Read the Docs' 빌드를 기반으로 Sphinx 문서를 호스팅하여 모든 버전에서 문서를 최신 상태로 유지할 수 있습니다. 이 두 도구는 개발자와 기술 문서 작성자가 최종 사용자에게 가장 적합한 사용자 문서를 작성하는 데 사용할 수 있는 훌륭한 도구입니다.
Sphinx에는 문서를 여러 언어로 번역하는 지원이 포함되어 있습니다. 문서 관리에 사용할 버전 제어를 지원합니다. 누구나 수정할 수 있고 올바른 정보를 추가하지 못하는 현재 위키와 달리 이 버전 제어 시스템에서는 모든 변경사항이 먼저 검토된 후 기본 저장소에 병합됩니다. 버전 제어를 사용하면 사용자가 문제를 만들고, 풀 리퀘스트를 열 수 있으므로 문서를 통해 프로젝트에 대한 오픈소스 참여도 증가합니다. Sphinx 및 Read the 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/ko/latest/](https://vlc-user-documentation-demo.readthedocs.io/ko/latest/)에서 확인할 수 있습니다.
제안된 문서 구조
VLC 사용자 문서의 구조를 만들었습니다. 여기(https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing)에서 확인할 수 있습니다. 새로운 구조를 적용하기 전에 멘토의 승인을 받아야 합니다. 즉, 멘토가 검토한 후에 구조가 변경될 가능성이 높습니다.
프로젝트 목표
- 문서 구조를 변경합니다.
- 최신 버전의 VLC에 맞게 문서를 업데이트합니다.
- Sphinx 및 ReadtheDocs를 사용하여 사용자 문서를 Gitlab로 이전합니다.
- 더 이상 사용되지 않는 이미지와 정보를 삭제합니다.
- 이해하기 쉽게 사용자 문서를 다시 작성합니다.
- Sphinx 국제화를 사용하여 번역을 위해 설정합니다.
- 사용자가 문서를 읽는 동안 발생한 문제를 신고하거나 해결할 수 있도록 문서 커뮤니티를 운영합니다.
이 프로젝트를 만든 이유
코드를 작성하고, 문제를 해결하고, 소프트웨어를 빌드하는 능력은 글쓰기를 통해 다른 사람에게 계몽을 할 수 있을 때 최대한의 잠재력을 발휘할 수 있다고 늘 믿었습니다. 저는 개인적으로 멀티미디어를 위한 무료 소프트웨어 솔루션을 만드는 데 VideoLAN 커뮤니티가 기울인 노력에 항상 매료되어 왔습니다. 어렸을 때 VLC 미디어 플레이어는 음악을 듣거나 영화를 볼 때 항상 사용하는 소프트웨어였습니다. 소리가 매우 크고 다양한 기능으로 구성되어 있었기 때문입니다. 어린 시절의 멋진 활동을 훌륭하게 만들어 준 지역 사회와 함께 일할 수 있어 영광일 것입니다.
내가 이 프로젝트에 적합한 이유
다음과 같은 이유로 이 프로젝트에 적합한 인재라고 생각합니다.
- 과거에 조직의 문서를 개선한 경험이 있고 모든 버전 제어 시스템을 사용할 수 있으므로 Gitab에서 명령어를 실행하는 것은 문제가 되지 않을 것입니다. 또한 사람들에게 가치를 창출하는 프로젝트에 참여하는 것이 저를 움직이는 원동력입니다.
- 누군가가 가능한 한 가장 효율적인 방법으로 일을 하기를 원한다면 그것을 문서화하는 것입니다. 프로세스를 문서화하면 관련된 모든 사람에게 효율성, 일관성 및 안전을 보장합니다.
- 저도 VLC 사용자 중 한 명으로서 VLC 사용자의 요구사항을 잘 알고 있습니다. 이렇게 하면 전 세계의 모든 사용자가 한눈에 이해할 수 있는 문서를 작성할 수 있습니다.