이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- VLC
- 테크니컬 라이터:
- 아비
- 프로젝트 이름:
- 하나의 모바일 포트에 대한 VLC 사용자 문서 만들기 (Android)
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
추상
사용자 문서는 최종 사용자를 지원하기 위한 정적 지원 시스템으로 사용됩니다. 제품 또는 서비스에 대한 기술적 정보와 비기술적 정보를 모두 제공합니다. 사용자가 소프트웨어 또는 서비스 사용 방법을 배우는 데 도움이 됩니다. 사소한 지시, 도움말 또는 요령만 있으면 지원팀에 문의하거나 이메일 답장을 기다리는 것을 원하지 않는 사람이 있을 수 있습니다. 사용자 문서가 바로 이를 수행합니다. 또한 지원 비용을 절감하며 제품 상태와 개발자팀의 정체성을 확립합니다.
Android용 VLC는 Google Play 스토어에서만 1억 회 이상 다운로드되었습니다. VLC는 오디오-동영상 재생에서 네트워크 스트림에 이르기까지 모바일 포트에 여러 기능을 제공합니다. 많은 사람들이 이러한 멋진 기능을 사용하고 싶지만 그렇게 할 수 없습니다. 이를 위해 블로그나 임의의 동영상을 검색하려면 많은 시간과 인내심이 필요하지만 획득한 정보의 신뢰성이 아직 없습니다. 현재 VLC는 위키 페이지에서 Android용 VLC 사용자 문서를 호스팅하고 이러한 기능에 대한 설명을 거의 또는 전혀 제공하지 않습니다. 또한 위키 페이지도 2019년 3월에 최종 업데이트되었습니다. 현재 프로젝트에서는 Android 포트에 최신 디자인과 사용 편의성을 더한 새로운 사용자 문서를 제공합니다.
현재 상황
위키 페이지는 완전히 오래되었으며 최신 버전의 VLC에 대한 정보가 거의 없습니다. 또한 탐색도 쉽지 않습니다. 영어가 아닌 다른 언어로 문서를 읽을 수 있는 옵션은 없습니다. 기능 설명이 전혀 포함되어 있지 않습니다.
분석
-> 현재 이 문서는 더 이상 사용되지 않으므로 다른 플랫폼과 도구를 사용하여 새로운 방식으로 작성해야 합니다.
-> 대부분의 Android 사용자는 기술적인 지식이 거의 없거나 전혀 없습니다. 하지만 기능에 대한 보다 기술적인 정보가 필요한 사람이 있습니다. 위의 각 목적을 위해 두 개의 개별 문서를 작성하고 유지 관리하는 것은 좋은 생각이 아닙니다. 또는 같은 문서에서도 기술 및 비기술 기준에 따라 기능을 나누는 경우에도 추가적인 혼동이 발생할 수 있습니다. 다시 한번 대부분의 사용자는 자신이 보는 UI나 사용하는 기능에 익숙하기 때문에 모든 사용자가 기술적인지 비기술적인지 판단하기는 쉽지 않습니다. 고객을 위해 이를 단순화하고자 합니다.
-> 대부분의 사용자는 스마트폰을 통해 정보를 얻고 데스크톱이나 다른 기기를 통해 쉬려고 합니다. 따라서 모든 화면 크기에 맞게 문서를 쉽게 조정할 수 있어야 합니다. 탐색에 관한 혼동을 일으키지 않아야 합니다.
-> 데스크톱 버전의 모든 기능이 Android 포트에서 제공되는 것은 아니며, 사용 가능한 경우 두 포트에서 모두 동일하게 작동하지 않습니다. 이는 데스크톱 애플리케이션이 훨씬 더 오래 개발되어 포화 상태가 되었기 때문입니다. 반면에 모바일 포트는 비교적 최근에 개발되었으며 아직 개발 중입니다. 그 외에도 오늘날의 휴대기기가 점점 더 강력해지고 있지만, 대부분 최종 사용자의 요구로 인해 통합할 수 있는 기능의 유형에 대한 분명한 제한이 있습니다. 아무도 사용하지 않는 기능을 보유하면 개발 리소스가 낭비됩니다. 따라서 기능을 기준으로 두 문서를 대화하지 않는 것이 좋습니다.
위의 분석을 토대로 다음을 제안합니다. 1. 현재 데스크톱 사용자 문서에서는 Sphinx 문서 생성기와 문서 읽기 테마를 사용하고 있습니다. Android 포트에 동일한 템플릿을 사용하면 다음과 같은 이점이 있습니다. -> 두 문서를 쉽게 병합합니다. -> 모든 화면 크기에 최적화되어 있습니다. -> 데스크톱 문서를 통해 Android 사용자 문서로 이동할 때 원활한 경험 제공
- 적용 시점의 상대적인 위치에 따라 챕터, 섹션, 하위 섹션을 구분합니다. 예를 들어 배경/PiP 모드는 더보기 -> 설정-> 동영상 내에 있으므로 챕터 구조는 다음과 같습니다.
- 더보기
- |__설정
- | |__미디어 라이브러리
- | |__Video -->배경/PiP 모드
- : -> 이 접근 방식을 사용하면 사용자가 애플리케이션의 상대적 위치와 비교하여 도움이 필요한 부분으로 쉽게 이동할 수 있으므로 액세스 편의성이 향상됩니다. 각 기능에서 기술 부분과 기술 외 부분을 추가로 분리할 수 있습니다. 먼저 기술적이지 않은 간단한 설명을 작성한 다음 동일한 기능의 기술적인 부분(있는 경우) 바로 아래에 이를 추가로 강조 표시하거나 라벨을 지정합니다. 이로 인해 약간의 반복이 발생할 수 있지만 비기술적 대다수의 경우 원활한 경험을 보장합니다. 이는 앞으로 유지관리 가능성을 높여 향후에도 도움이 될 것입니다. 애플리케이션이 채도 상태에 도달하면 상대적 UI가 많이 변경될 가능성이 낮으므로 향후 새 기능이 추가/삭제되는 경우 섹션을 리팩터링하면 됩니다. 전체 UI가 변경되는 경우 섹션/챕터를 재정렬하거나 전체 문서를 재구성할 수 있습니다. 두 경우 모두 현재 UI와 일치하도록 스크린샷을 교체해야 하므로 전체 문서를 수정해야 합니다. 실제 데모는 다음 링크에서 확인하실 수 있습니다. https://avinal.gitlab.io/vlc-android-docs/
문서의 각 섹션은 레이블이 지정된 스크린샷 , 기능 설명, 보다 기술적인 부분(있는 경우), 기능에 대한 도움말 및 유용한 정보로 구성됩니다.
-> 데스크톱에서 사용자 문서를 독립적으로 개발하면 현재 문서에 영향을 주거나 개발 중에 영향을 받지 않고 단 몇 단계만으로 두 문서를 병합하는 데 도움이 됩니다. 개발된 데스크톱 문서의 Android 섹션에 전체 문서를 넣고 Android용 VLC 문서의 퍼머링크를 만드는 것이 좋습니다.
-> 데스크톱 사용자 문서의 시작 페이지를 새롭게 디자인하여 사용자가 즐겨 찾는 OS를 직접 선택할 수 있도록 하고 선택한 OS의 문서로 리디렉션하는 등의 개선이 이루어질 예정입니다. Windows, MacOS 및 Linux VLC 사용자 설명서는 이미 잘 설계되어 있고 반대의 경우가 있으므로, Windows/MacOS/Linux 또는 Android 또는 iOS 중에서 선택할 수 있는 옵션을 마련할 수도 있습니다. 이렇게 하면 모든 포트에 사용할 수 있는 링크 하나만 포함된 잘 분리되어 있지만 통합된 사용자 문서가 생성됩니다.
제안된 사용자 문서가 더 나은 이유는 무엇인가요? 제안된 사용자 도움말은 최종 사용자가 도움을 요청하는 일반적인 패턴을 기반으로 하여 구성되어 있습니다. 이 문서에는 사용 편의성과 최종 사용자 환경을 극대화하기 위해 단순성, 명확성, 디자인과 분위기, 기술적 지식과 같은 필수 기능이 모두 포함되어 있습니다. 또한 더 이상 모든 포트에 대해 개별 사용자 문서를 유지 관리할 필요가 없으므로 쉽게 유지관리할 수 있습니다.
이 프로젝트의 담당자가 되는 이유는 무엇인가요? -> 코드를 작성한 지 2년이 되어가면서 특정 라이브러리 또는 일부 소프트웨어의 API 문서를 검토하거나 내 코드를 문서화해야 하는 경우가 종종 있습니다. 따라서 사람들이 문서에서 보고 싶어하는 부분, 직면한 문제, 도움을 얻기 위해 어떻게 접근하는지 정확하게 알고 있습니다. 동일한 경험을 적용하여 일관되고 쉽게 읽을 수 있는 문서를 작성할 수 있습니다.
-> 저는 Quora, Stack Overflow, 기타 다양한 플랫폼에서 기술 관련 글을 적극적으로 쓰고 있습니다. 기억하기 쉽고 사람들이 쉽게 이해할 수 있는 방식으로 설명하는 방법을 알고 있습니다.
-> Android용 VLC는 강력하고도 유명한 도구이지만, 대부분의 기능은 알려지지 않았거나 도움을 받을 수 없습니다. 저는 몇 년 동안 데스크톱 및 모바일 플랫폼 모두에서 VLC를 사용해 왔으며 사용자에게 어떤 문제가 발생할 수 있는지 알고 있습니다. 나의 모든 지식과 경험을 활용하여 훌륭한 문서를 만들 수 있습니다.