На этой странице содержится подробная информация о проекте технического написания, принятом для участия в 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/Documentation:Command_line/ [8] https://trac.videolan .org/vlc/ticket/35