이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- VLC
- 테크니컬 라이터:
- Avii
- 프로젝트 이름:
- 모바일 포트 (Android) 1개에 관한 VLC 사용자 문서 만들기
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
추상
사용자 문서는 최종 사용자를 지원하는 정적 지원 시스템으로 사용됩니다. 제품 또는 서비스에 대한 기술적 정보와 비기술적 정보를 모두 제공합니다. 사용자가 소프트웨어 또는 서비스를 사용하는 방법을 학습하는 데 도움이 됩니다. 약간의 안내, 도움말, 요령만 있으면 되는 사용자는 지원팀에 문의하거나 이메일 답장을 기다리기를 원하지 않을 수 있습니다. 사용자 문서가 이를 수행합니다. 또한 지원 비용을 절감해 주며 제품 건전성 및 개발팀의 일원이 될 수 있습니다.
Android용 VLC는 Google Play 스토어에서만 1억 번 이상 다운로드되었습니다. VLC는 오디오-동영상 재생에서 네트워크 스트림에 이르기까지 모바일 포트에 다양한 기능을 제공합니다. 사람들은 이러한 멋진 기능을 사용하고 싶지만 사용할 수 없는 경우가 많습니다. 블로그나 무작위 동영상을 검색하려면 많은 시간과 인내심이 필요하며, 그래도 얻은 정보의 진위 여부를 알 수 없습니다. 현재 VLC는 위키 페이지에서 Android용 VLC 사용자 문서를 호스팅하며 이러한 기능에 대한 설명은 거의 또는 전혀 제공하지 않습니다. 또한 위키 페이지는 2019년 3월에 마지막으로 업데이트되었습니다. 현재 프로젝트는 최신 디자인과 더 나은 사용 편의성을 갖춘 Android 포팅용 새 사용자 문서를 제공합니다.
현재 상황
위키 페이지는 완전히 오래되었으며 최신 버전의 VLC에 관한 정보가 거의 포함되어 있지 않습니다. 또한 탐색하기가 쉽지 않습니다. 영어가 아닌 다른 언어로 문서를 읽을 수 있는 옵션이 표시되지 않습니다. 기능 설명은 전혀 포함되어 있지 않습니다.
분석
-> 현재 문서는 더 이상 사용되지 않으며 새로운 방식으로 작성하고 다른 플랫폼과 도구를 사용해야 합니다.
-> 대부분의 Android 사용자는 기술 지식이 거의 없거나 전혀 없습니다. 그러나 기능에 대한 더 많은 기술적 정보가 필요한 사람들도 있습니다. 위의 목적별로 두 개의 별도 문서를 작성하고 유지하는 것은 좋지 않습니다. 또는 동일한 문서에서 기술적 기능과 비기술적 기능을 기준으로 기능을 구분하면 혼란이 가중됩니다. 대부분의 사용자는 표시되는 UI나 사용하는 기능에 익숙하므로 모든 사용자가 기술적 문제인지 아닌지 쉽게 판단할 수 없습니다. 따라서 이를 간소화하고자 합니다.
-> 대부분의 사용자는 스마트폰 자체를 통해 정보를 얻고 나머지는 데스크톱이나 다른 기기를 통해 얻으려고 합니다. 따라서 문서는 모든 화면 크기에 쉽게 조정할 수 있어야 합니다. 탐색에 관한 혼란을 유발해서는 안 됩니다.
-> 데스크톱 버전의 일부 기능은 Android 포트에서 사용할 수 없으며, 사용 가능한 경우에도 두 포트에서 동일하게 작동하지 않습니다. 이는 데스크톱 애플리케이션이 훨씬 오래 개발되어 일종의 포화 상태에 도달한 반면 모바일 포팅은 비교적 새롭고 아직 개발 중이기 때문입니다. 그 외에도 요즘 휴대기기가 점점 강력해지고 있지만, 대부분 최종 사용자의 수요로 인해 통합할 수 있는 기능 유형에 명확한 제한이 있습니다. 아무도 사용하지 않는 기능은 개발 리소스 낭비입니다. 따라서 기능을 기준으로 두 문서를 모두 대화하는 것은 권장하지 않습니다.
위 분석을 바탕으로 다음을 제안합니다. 1. 현재 데스크톱 사용자 문서에서는 Sphinx 문서 생성기와 Read the Docs 테마를 사용하고 있습니다. Android 포트에도 동일한 이름을 사용하면 다음과 같은 이점이 있습니다. -> 두 문서를 쉽게 병합할 수 있습니다. -> 모든 화면 크기에 최적화되어 있습니다. -> 데스크톱 문서를 통해 Android 사용자 문서로 이동할 때 원활한 환경
- 애플리케이션에서의 상대적 위치에 따라 장, 섹션, 하위 섹션을 구분합니다. 예를 들어 백그라운드/PiP 모드는 더보기 -> 설정 -> 동영상에 있으므로 챕터 구조는 다음과 같습니다.
- 더보기
- |__설정
- | |__미디어 라이브러리
- | |__동영상 --> 백그라운드/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를 사용해 왔으며 사용자에게 어떤 문제가 발생할 수 있는지 잘 알고 있습니다. 모든 지식과 경험을 종합하여 우수한 문서를 작성할 수 있습니다.