Как внести свой вклад в пользовательскую документацию Joomla

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

Каждый пользователь может помочь в создании более качественной пользовательской документации для Joomla! Основная цель на текущем этапе — улучшение содержания, чтобы сделать руководства максимально полными и удобными для тех, кто только начинает знакомство с системой.

Несколько лет назад Клиффорд Форд реорганизовал пользовательскую документацию из вики-формата в JDocManual. В начале этого года содержимое этого руководства было перенесено на тестовую площадку docs-core.sandbox.joomla.org. Сейчас ведется работа по преобразованию алфавитной структуры в логический поток, позволяющий поэтапно изучать Joomla, а также выявляются и заполняются пробелы в существующих материалах.

Существует три основных направления, где может пригодиться ваша помощь:

• Написание нового контента: Любой пользователь может добавлять новые материалы, особенно обучающие руководства для начинающих. Для этого существует список задач, над которыми можно работать время от времени.
• Обработка материалов: Необходимы люди, готовые на регулярной основе уделять время структурированию contributed материалов, улучшению технического качества текстов и согласованию размещения контента.
• Техническая реализация и поддержка: Требуются специалисты для доработки функционала сайта документации и его обслуживания.

Добавление нового контента

Создание пользовательской документации — задача не только для программистов. Чтобы материалы были понятны не-техническим пользователям, к их созданию должны привлекаться самые обычные пользователи Joomla. И что особенно важно — каждый может помочь. Если вы сами недавно начали работать с Joomla, ваш взгляд особенно ценен, так как вы можете лучше других оценить, насколько документация понятна для новичков.

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

Пошаговая инструкция по добавлению контента

1. Создайте учетную запись на тестовом сайте. Иногда возникают проблемы с отправкой подтверждающего email; эта проблема решается. Совет: если у вас есть аккаунт на Github, и вы используете то же имя пользователя для этой учетной записи, в дальнейшем вы сможете входить на сайт через Github.
2. Перейдите в канал «Documentation Suggestions» на Mattermost и запросите разрешение на написание статей. Сообщите имя пользователя, которое вы использовали при регистрации.
3. После получения прав автора вы можете войти в систему.
4. Ознакомьтесь со списком задач для документации на GitHub: github.com/joomla/documentation/issues. Если у вас есть аккаунт на GitHub, вы можете отметить в задаче, что работаете над ней, чтобы избежать дублирования усилий. Все вопросы и обсуждения по теме также можно вести там. Если у вас нет аккаунта на GitHub, просто сообщите об этом в канале «Documentation Suggestions» на Mattermost.
5. Начинайте писать! Черновик не будет виден другим до тех пор, пока вы не отправите его на рецензирование. Вам не нужно беспокоиться о точном месте размещения вашего материала: этим займутся Кураторы Документации.

Как видно, для коммуникации по вопросам документации используется GitHub. Без учетной записи на GitHub вы можете только читать обсуждения, но не участвовать в них. Создать аккаунт несложно, и он может быть очень полезен для различных видов contributions в Joomla, например, для тестирования исправлений ошибок.

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

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

Обработка материалов, контроль структуры и качества

Идея проекта в том, чтобы не обременять авторов начального контента такими деталями, как точное размещение материалов в руководствах или финальная шлифовка текста перед публикацией. Для этого предполагается, что некоторые волонтеры специализируются на обработке взаимодействий. Такая команда, условно называемая «Кураторы Документации», будет проходить обучение и постепенно входить в роль. Эта небольшая группа будет следить за общей структурой и доводить содержание до идеального состояния, координируя усилия в ходе коротких двухнедельных совещаний.

Техническая реализация и поддержка

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

• Workflow (Рабочий процесс): В проекте используется встроенный в Joomla workflow. Требуется внести некоторые корректировки для повышения удобства, например, настройку отправки уведомлений автору при смене стадии статьи, создание плагина для управления видимостью материала и автоматизацию некоторых свойств при его размещении. Аналогичные доработки востребованы для сайтов Joomla Magazine и Enhanced Guided Tours, поэтому формируется отдельная группа для их реализации.
• Версионирование (Versioning): Используется встроенная система версий Joomla, но некоторые аспекты можно улучшить, например, экран сравнения различий между версиями. Также есть планы по интеграции версионирования из GitHub в Joomla.
• Веб-сайт: Требуется веб-мастер для регулярного технического обслуживания, включая обновления Joomla и резервное копирование. Кроме того, нужны доработки CSS и/или override'ов для улучшения отображения меню в используемом шаблоне joomla.org.

Все это — конкретные проекты, которые планируется завершить в ближайшие месяцы. Таким образом, объем работы вполне обозрим и не потребует долгосрочных значительных временных затрат. Кто готов помочь с этим?