Эта страница переведена с помощью Cloud Translation API.

проект VLC

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:: ВЛК
Технический писатель:: Авии
Название проекта:: Создайте пользовательскую документацию VLC для одного мобильного порта (Android).
Длина проекта:: Стандартная продолжительность (3 месяца)

Описание Проекта

АБСТРАКТНЫЙ

Пользовательская документация используется как статическая система поддержки для помощи конечным пользователям. Он предоставляет как техническую, так и нетехническую информацию о продукте или услуге. Это помогает пользователям научиться использовать программное обеспечение или услугу. Не каждый человек хочет обращаться в службу поддержки или ждать ответа по электронной почте, если все, что ему нужно, — это небольшое указание, совет или подсказка. Пользовательская документация как раз и делает это. Это также снижает затраты на поддержку и является показателем работоспособности продукта и команды разработчиков.

Только из магазина Google Play VLC для Android было загружено более 100 миллионов раз. VLC предоставляет множество функций для своих мобильных портов, от воспроизведения аудио-видео до сетевого потока. Часто люди хотят использовать эти замечательные функции, но не могут этого сделать. Поиск блога или какого-то случайного видео для этого требует много времени и терпения и все равно достоверности полученной информации нет. В настоящее время VLC размещает пользовательскую документацию VLC для Android на вики-странице и практически не предоставляет описания этих функций. Кроме того, вики-страницы последний раз обновлялись в марте 2019 года. Текущий проект предоставит новую пользовательскую документацию с современным дизайном и большей простотой использования для порта Android.

ТЕКУЩАЯ СИТУАЦИЯ

Страницы вики полностью устарели и содержат очень мало информации о последней версии VLC. Кроме того, по ним нелегко ориентироваться. Нет видимой возможности прочитать документацию на другом языке, кроме английского. Он вообще не содержит описания функций.

АНАЛИЗ

-> На данный момент текущая документация устарела и ее необходимо писать по-новому, используя другую платформу и инструменты.

-> Большинство пользователей Android практически не имеют технических знаний. Но есть люди, которым нужна дополнительная техническая информация о функции. Написание и поддержка двух отдельных документов для каждой из вышеперечисленных целей — не лучшая идея. Или даже в одной и той же документации разделение функций на технические и нетехнические создает дополнительную путаницу. Поскольку, опять же, большинство пользователей привыкли к пользовательскому интерфейсу, который они видят, или к функциям, которые они используют, не всем легко решить, является ли что-то техническим или нетехническим. Поэтому мы хотели бы упростить это для них.

-> Большинство пользователей попытаются получить информацию через свой смартфон, а остальные — через настольный компьютер или другие устройства. Таким образом, документация должна быть легко адаптирована к любому размеру экрана. И не должно создавать путаницы в навигации.

-> Не все функции настольной версии доступны в порту Android, и если они доступны, они не работают одинаково в обоих портах. Это связано с тем, что настольное приложение находится в разработке гораздо дольше и достигло своего рода состояния насыщения, в то время как мобильный порт является относительно новым и все еще развивается. Помимо этого, хотя современные мобильные устройства становятся все более мощными, существует очевидное ограничение на тип функций, которые мы можем включить, в основном из-за требований конечного пользователя. Наличие функции, которую никто не использует, — это пустая трата ресурсов на разработку. Поэтому просматривать обе документации на основе функций не рекомендуется.

НА ОСНОВЕ ИЗВЕДЕННОГО АНАЛИЗА ПРЕДЛАГАЮ СЛЕДУЮЩЕЕ. 1. На данный момент пользовательская документация Desktop использует генератор документации Sphinx и тему «Чтение документов». Использование того же самого для порта Android поможет нам следующим образом: -> Простое объединение обеих документов. -> Он оптимизирован для всех размеров экрана. -> Беспрепятственный переход к пользовательской документации Android через настольную документацию.

Разделение глав, разделов и подразделов в зависимости от их относительного положения в приложении. Например, режим «Фон/PiP» находится внутри «Дополнительно» -> «Настройки» -> «Видео», поэтому структура главы будет такой:
Более
|__Настройки
| |__Медиа-библиотека
| |__Видео -->Фоновый режим/режим PiP
: -> Этот подход улучшит доступность, поскольку пользователи смогут легко перейти к той части, где им нужна помощь, сравнивая ее с относительным местоположением в приложении. Для каждой функции мы можем дополнительно разделить техническую и нетехническую части. Сначала мы напишем простое нетехническое описание, а затем выделим или отметим технические части той же функции, если таковые имеются, чуть ниже нее. Это может привести к некоторому повторению, но обеспечит беспрепятственный опыт нетехнического большинства. Это также поможет в будущем за счет повышения ремонтопригодности. Когда приложение достигнет состояния насыщения, относительный пользовательский интерфейс вряд ли сильно изменится, поэтому в будущем, если новая функция будет добавлена/удалена, мы можем просто реорганизовать раздел. В случае изменения всего пользовательского интерфейса мы можем изменить порядок разделов/глав или реструктурировать весь документ. В любом случае нам необходимо изменить всю документацию, поскольку необходимо заменить снимок экрана, чтобы он соответствовал текущему пользовательскому интерфейсу. Рабочая демо-версия размещена здесь: https://avinal.gitlab.io/vlc-android-docs/.
Каждый раздел документации должен состоять из помеченного снимка экрана, описания функции, дополнительной технической части, если таковая имеется, а также советов и рекомендаций по использованию этой функции.

-> Независимая разработка этой пользовательской документации с рабочего стола поможет нам объединить обе документации всего за несколько шагов, не затрагивая текущую документацию и не подвергаясь ее влиянию во время разработки. Я предлагаю разместить всю эту документацию в разделе Android документации для настольных компьютеров после ее разработки, а затем создать постоянную ссылку на документацию VLC для Android.

-> Дополнительные улучшения могут включать изменение дизайна стартовой страницы пользовательской документации рабочего стола, чтобы пользователи могли напрямую выбирать свою любимую ОС, а затем перенаправление к документации выбранной ОС. Поскольку пользовательская документация VLC для Windows, MacOS и Linux уже хорошо разработана и согласована, мы можем указать варианты на выбор: Windows/MacOS/Linux, Android или iOS. В результате вы получите хорошо разделенную, но унифицированную пользовательскую документацию с одной ссылкой для всех портов.

ПОЧЕМУ ПРЕДЛАГАЕМАЯ МОЯ ПОЛЬЗОВАТЕЛЬСКАЯ ДОКУМЕНТАЦИЯ ЛУЧШЕ? Предлагаемая пользовательская документация структурирована на основе общих шаблонов, которым следует следовать конечному пользователю при получении помощи. Документация сочетает в себе все необходимые функции, например, простоту, ясность, внешний вид и технологические знания, чтобы максимально упростить использование и удобство для конечного пользователя. Это также легко поддерживать, поскольку больше нет необходимости вести отдельную пользовательскую документацию для каждого порта.

ПОЧЕМУ Я ПОДХОДЮ ДЛЯ ЭТОГО ПРОЕКТА? -> Я пишу коды уже 2 года, и часто мне нужно просмотреть документацию API для определенных библиотек или какого-либо программного обеспечения или даже документировать свой собственный код. Поэтому я точно знаю, что люди хотят видеть в документации, с какой проблемой они сталкиваются и как они подходят к получению помощи. Я смогу применить тот же опыт для написания последовательной и легко читаемой документации.

-> Я активно писал технические материалы для Quora, Stack Overflow и других платформ. Я знаю, как объяснить вещи так, чтобы это было понятно и людям было легко понять.

-> VLC для Android — мощный и очень известный инструмент, однако большинство его функций либо неизвестны, либо помощь недоступна. Я использую VLC как на настольных, так и на мобильных платформах уже много лет и знаю, с какими проблемами может столкнуться пользователь. Объединив все свои знания и опыт, я могу гарантировать отличную документацию.