проект VLC

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

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

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

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

ТЕКУЩЕЕ СОСТОЯНИЕ ДОКУМЕНТАЦИИ

Пользовательская документация VLC находится в процессе модернизации и обновления. В настоящее время осуществляется переход от старой документации на основе Wiki[1] к современной пользовательской документации, созданной Sphinx[2], размещенной на ReadTheDocs.

ЦЕЛЕВАЯ АУДИТОРИЯ

Целевая аудитория — это как любопытные пользователи, желающие изучить возможности медиаплеера VLC за пределами обычного медиаплеера, так и в некоторой степени он также поможет разработчикам, выступая в качестве простого справочного руководства. Следовательно, я планирую включить как инструкции на основе графического пользовательского интерфейса (вместе с изображениями, где это необходимо), так и методы на основе CLI (вместе с фрагментами кода), чтобы у конечного пользователя была свобода выбора.

Я считаю, что язык документации (особенно раздела с графическим пользовательским интерфейсом) должен быть достаточно смягчен, чтобы человек, имеющий номинальный опыт работы на компьютерах, мог понять и реализовать руководство. С другой стороны, он не должен быть слишком длинным или пояснительным (особенно раздел CLI), чтобы программисты потеряли интерес.

Правильный баланс может быть достигнут путем упоминания предварительных требований в начале страницы или сохранения дополнительных разделов, которые опытные люди могут пропустить.

Целевой аудиторией для создания переводов являются разработчики/пользователи VLC, хорошо владеющие английским языком и языком, на который они будут переводить.

ИНСТРУМЕНТЫ

Новая документация создается Sphinx и размещается на ReadTheDocs, а система контроля версий реализована в GitLab. У меня был некоторый опыт использования Git и GitHub, который помог мне освоиться с GitLab, хотя были некоторые особенности, изучение которых потребовало некоторого времени.

Что касается Sphinx, я читал о нем, когда мой коллега-энтузиаст открытого исходного кода заметил, как много организаций используют его для создания своей документации (примечательным примером является Blender, который использует Sphinx для создания своих руководств пользователя[3] и документации API). [4]).

Я был немного знаком с ReadTheDocs — хорошим инструментом для управления версиями и размещения технической документации. Таким образом, я смог без особых проблем создать документацию VLC и знаком с reStructured Text, используемым форматированием.

Для переводов VLC использует Babel для создания файлов .po для реализации i18n и l10n. В настоящее время я знакомлюсь с рабочим процессом Babel и тем, как создавать файлы .mo с помощью Sphinx.

Я намерен использовать период склеивания для дальнейшего ознакомления с тонкостями вышеупомянутых инструментов.

РЕЗУЛЬТАТЫ И ЕЖЕНЕДЕЛЬНЫЕ СРОКИ

В рамках проекта 2019 года уже охвачены части «Установка», «Интерфейс», «Аудио», «Видео», «Воспроизведение» и т. д. (большая часть базовых функций). Следовательно, для проекта 2020 года я хотел бы обновить и поработать над разделом расширенного использования пользовательской документации.

РЕЗУЛЬТАТ 1 [Неделя 1–2]: Обновление документации по транскодированию, как указано в № 7[5].

  • Перекодировать
  • Перекодировать несколько видео
  • Добавить логотип
  • Объедините видео вместе
  • Извлечь аудио и извлечь аудио из файла
  • Копировать DVD

РЕЗУЛЬТАТ 2 [недели 3–4]: обновление с использованием VLC в качестве веб-плагина[6] при тестировании в Firefox 77, Chrome 83 и Edge 83.

  • Создание веб-страниц с видео
  • Встроить атрибуты тега
  • Описание API JavaScript

РЕЗУЛЬТАТ 3 [Неделя 5]: Протестируйте команды интерфейса командной строки[7] и обновите их соответствующим образом.

  • Потоки
  • Выбор модулей
  • Конкретные параметры товара
  • Фильтры

Неделя 6: Буферная неделя для трех вышеупомянутых результатов.

РЕЗУЛЬТАТ 4 [7-8 неделя]: Подготовьтесь к переводам. Помимо обновления, буду готовиться к переводам на другие языки. Это важно, поскольку после перевода пользователи без знания английского языка смогут прочитать документацию (и, кстати, VLC станет на шаг ближе к достижению мирового господства[8]).

Как упоминалось в разделе «Инструменты» предложения, VLC в настоящее время использует Babel для создания файлов .po для переводов. Я задокументирую процесс, позволяющий пользователю/добровольцу:

  • Загрузите и соберите базовую документацию локально.
  • Используйте Babel для создания необходимых файлов.
  • Введите переводы для строк.
  • Сборка переведенной документации с помощью Sphinx.
  • Зафиксируйте изменения.

РЕЗУЛЬТАТ 5 [Неделя 9–10]: Подготовка документации по модулям. Как обсуждалось с наставниками, я планирую подготовить документацию по модулям в двух частях.

Часть I: Создание файлов рядом с модулями с помощью сценария, который ищет допустимые параметры в базе кода и извлекает их однострочное использование (и значения по умолчанию) из соответствующих вики-страниц. Это послужит базовым проектом.

Часть II: Создание структуры, специфичной для платформы, которая связывает все модули+плагины+опции для конкретной платформы (Windows, а если позволяет время, также и для Fedora).

Создание файлов рядом с модулями обеспечит близость документации к исходному коду. При использовании подхода «снизу вверх» основная документация по модулям будет создана путем объединения файлов, созданных в Части I, и использования структуры, созданной в Части II, в качестве справочной информации.

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

БОНУСНАЯ ДОСТАВКА [11-я неделя]: подготовьтесь к выпуску версии 4.0. В случае, если проект пойдет по графику, я хотел бы предложить бонусный результат. Как обсуждалось с наставниками, подготовка к выпуску 4.0 подразумевает наличие стабильной и практически полной документации для версии 3.0.

Следовательно, я бы просмотрел уже заполненную документацию следующих разделов, чтобы проверить и обновить упомянутые методы:

  • Основное использование: мультимедиа, воспроизведение, аудио, видео, субтитры, горячие клавиши, записи, настройки, советы и подсказки.
  • Расширенное использование: проигрыватель, интерфейс, транскодирование, потоковая передача, необычные случаи.
  • Дополнения: Расширения, Скины.

Неделя 12: Буферная неделя для трех вышеуказанных результатов + итоговые отчеты.

ПОЧЕМУ Я ПОДХОДЮ ДЛЯ ЭТОГО ПРОЕКТА?

Как технический энтузиаст, у меня есть опыт использования/тестирования программного обеспечения, и иногда я пытаюсь понять смысл их кодовой базы. Фактически, пытаясь понять кодовую базу организации с открытым исходным кодом, я впервые по-настоящему осознал важность документации. Кроме того, как любитель музыки, я имею большой опыт настройки VLC :)

Кроме того, я всю жизнь был исследователем и писателем. Если я что-то не записываю, я никогда по-настоящему этого не понимаю, и эта привычка сделала меня эффективным конспектором и документатором.

Пересечение этих двух привычек делает меня подходящим специалистом по технической документации. Я могу разобраться в технических аспектах, а также документировать свои выводы/процессы так, чтобы они были понятны пользователям.

Ссылки: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https:// docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org /Документация:Командная_строка/ [8] https://trac.videolan.org/vlc/ticket/35