Проект ВидеоЛАН

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

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

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

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

АБСТРАКТНЫЙ

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

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

На момент написания этой статьи к пользовательской документации VLC обращались 4 634 065 раз, а медиаплеер VLC загружали примерно 23 миллиона раз в месяц с основного веб-сайта. Это показывает, что многие люди во всем мире используют VLC Media. Player и, возможно, захотите прочитать его пользовательскую документацию для получения инструкций по использованию медиаплеера. Однако пользовательская документация медиаплеера VLC в настоящее время устарела и неполна (последний раз она была изменена 28 октября 2015 г.), и сообщество VideoLAN хочет использовать этот проект для улучшения своей пользовательской документации, чтобы конечные пользователи могли беспрепятственно работать при с помощью медиаплеера VLC.

ТЕКУЩЕЕ СОСТОЯНИЕ

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

ПОЧЕМУ ПРЕДЛАГАЕМАЯ ПОЛЬЗОВАТЕЛЬСКАЯ ДОКУМЕНТАЦИЯ ЯВЛЯЕТСЯ УЛУЧШЕНИЕМ ПО СРАВНЕНИЮ С ТЕКУЩЕЙ?

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

Наставники: Жан-Батист, Алекс, Симон

АНАЛИЗ

Мы с Жаном-Батистом поговорили о новой среде, в которую будет перенесена текущая пользовательская документация для улучшения, и он поделился двумя ссылками, которые показывали репозиторий Gitlab с исходным файлом, написанным с помощью Sphinx, и основную документацию, размещенную на сайтах Read the Docs и он сказал, что они ожидают, что новая документация будет похожа на нее. Я много исследовал эти инструменты, чтобы лучше понять, как они работают.

Сфинкс

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

Прочтите документацию

Read the Docs упрощает документацию по программному обеспечению, автоматизируя создание, управление версиями и размещение ваших документов. Он никогда не выходит из синхронизации; то есть всякий раз, когда вы отправляете код в свою любимую систему контроля версий, будь то Git, Mercurial, Bazaar или Subversion, Read the Docs автоматически создаст ваши документы, чтобы ваш код и документация всегда были актуальными. У него есть несколько версий; Read the Docs может размещать и создавать несколько версий ваших документов, поэтому иметь версию ваших документов 1.0 и версию ваших документов 2.0 так же просто, как иметь отдельную ветку или тег в вашей системе контроля версий. Read the Docs — бесплатная программа с открытым исходным кодом, в которой размещена документация почти для 100 000 больших и малых проектов с открытым исходным кодом практически на всех человеческих и компьютерных языках.

ВЕРДИКТ

Sphinx — невероятно мощный инструмент, созданный на его основе Read the Docs и предоставляющий хостинг для документации Sphinx, который поддерживает актуальность ваших документов во всех версиях. Вместе они представляют собой замечательный набор инструментов, которые разработчики и технические писатели могут использовать для создания пользовательской документации, наиболее подходящей для конечных пользователей.

Sphinx включает поддержку перевода документации на несколько языков. Он поддерживает контроль версий, который будет использоваться для управления документацией. В отличие от нынешней вики, где каждый может редактировать, но не добавлять нужную информацию, эта система контроля версий гарантирует, что все изменения сначала проверяются, прежде чем они будут объединены в основной репозиторий. Контроль версий также увеличит вклад документации в проект с открытым исходным кодом, поскольку люди могут создавать проблемы, открывать запросы на включение и т. д. Sphinx и читать документацию используют список других замечательных сообществ, таких как; ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs и т. д., и это отличный инструмент для создания новой пользовательской документации VLC.

Я не просто прочитал об этих инструментах, я еще и создал базовый образец. Это ссылка: https://gitlab.com/Didicodes/demo-vlc-user-documentation на мой репозиторий Gitlab, а размещенную версию на readthedocs можно найти здесь: [https://vlc-user-documentation-demo. readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.

СТРУКТУРА ПРЕДЛАГАЕМОЙ ДОКУМЕНТАЦИИ

Я создал структуру пользовательской документации VLC, которую можно найти здесь; https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing . Прежде чем начать внедрение этой новой структуры, она должна быть одобрена наставниками. Это означает, что структура, скорее всего, изменится после того, как она будет рассмотрена наставниками.

ЦЕЛИ ПРОЕКТА

  • Реструктуризировать документацию.
  • Обновите документацию, чтобы она соответствовала современным версиям VLC.
  • Перенесите пользовательскую документацию в Gitlab с помощью Sphinx и ReadtheDocs.
  • Удалите устаревшие изображения и информацию.
  • Перепишите пользовательскую документацию, чтобы ее было легче понять.
  • Настройте его для перевода с помощью Sphinx Internationalization.
  • Сделайте сообщество документации управляемым, чтобы пользователи могли сообщать о любых проблемах, возникающих при чтении документации, или решать их.

ПОЧЕМУ ЭТОТ ПРОЕКТ?

Я всегда был убежден, что написание кода, решение проблем и создание программного обеспечения полностью раскрывают свой потенциал, когда у вас также есть возможность просвещать других об этом посредством письма. Лично меня всегда восхищали усилия сообщества VideoLAN по созданию бесплатных программных решений для мультимедиа. В детстве медиаплеер VLC всегда был тем программным обеспечением, которое я использовал при прослушивании музыки или просмотре фильмов, потому что он был очень громким и имел множество функций. Для меня будет честью работать с сообществом, которое сделало мое детство замечательным.

ПОЧЕМУ Я ПОДХОДЮЩИЙ ЧЕЛОВЕК ДЛЯ ЭТОГО ПРОЕКТА

Я считаю, что я подходящий человек для этого проекта, потому что:

  • У меня есть прошлый опыт улучшения документации организаций и я могу использовать любую систему контроля версий, поэтому выполнение команд на Gitab не будет проблемой. Более того, меня движет работа над проектами, которые приносят пользу людям.
  • Я считаю, что если вы хотите, чтобы кто-то сделал что-то максимально эффективно, вы это документируете. Документируя свои процессы, вы обеспечиваете эффективность, последовательность и спокойствие для всех участников.
  • Я знаю потребности пользователей VLC, потому что я один из них. Это позволит написать документацию таким образом, чтобы ее понял с первого взгляда любой другой пользователь по всему миру.