16 апреля 2019 в 16:24
На нашем сайте несколько раз предпринимались попытки создать руководство по Drupal. Однако эта задача слишком большая. В одиночку создать исчерпывающую документацию и постоянно поддерживать ее в актуальном состоянии, думаю, и невозможно.
Помимо грандиозных масштабов задачи возникает и множество вопросов:
- Какие темы стоит затронуть в первую очередь?
- Что наиболее интересно начинающим и продвинутым друпалерам?
- Каким должен быть формат документации: краткие заметки или лонгрид?
- Не «утонет» ли статья в трекере через пару недель?
- Как структурировать информацию?
- И многие другие.
Участники нашего сообщества периодически делятся своим опытом, пишут интересные и полезные статьи. К сожалению, до настоящего времени на нашем сайте не было инструмента, с помощью которого можно было бы собрать все полезные материалы в одном месте и структурировать их.
Мы решили добавить на сайт новый раздел, который будет называться «Документация». Ниже будут представлены предварительные результаты обсуждения в репозитории проекта.
Описываемая ниже функциональность пока недоступна для использования, так как реализована только в локальном окружении. Перенос на сайт будет сделан после обсуждения здесь, доработке нескольких моментов и добавлению идей, которые, я очень надеюсь, будут высказаны вами.
Функциональность раздела «Документация»
- Новый словарь категорий документации, пополняемый редакцией сайта на основе данных Яндекс.Метрики и предложений участников сообщества
- Новый тип материала «Документация»
- Новая страница /docs для отображения категорий, опубликованных материалов и «рекомендуемых» тем для документации
- Ранее опубликованные интересные и актуальные статьи будут конвертированы в новый тип материала
- Любой зарегистрированный пользователь сможет добавить материал в раздел
- Любой зарегистрированный пользователь сможет добавить комментарий к материалам
- Будет создана новая роль «Модератор документации» с правами на изменение материалов в разделе
- Новые материалы, созданные участниками будут сохраняться в неопубликованном виде и не будут отображаться в списке
- Одобренные материалы будут публиковаться и выводиться в разделе в виде ссылок
- Для некоторых категорий будут созданы «рекомендуемые темы», которые будут отображаться в виде текста под списком опубликованных материалов
- При наведении на название категории будет появляться иконка добавления материала в категорию. Клик на иконку у категории откроет форму создания ноды с заполненным полем категории документации.
- При наведении на предложенную тему будет появляться иконка добавления материала. Клик на иконку у предложенной темы откроет форму создания ноды с заполненным заголовком и полем категории документации
Несколько скриншотов
Главная страница раздела «Документация»
Пояснения к главной странице раздела «Документация»
После клика на иконку у категории
После клика на иконку у предложенной темы
Друзья, нам важно узнать ваше мнение о создаваемом разделе! Напишите, пожалуйста, ваши мысли, идеи и вопросы.
Комментарии
Также напомню о https://www.drupal.org/docs/user_guide/en/index.html
который содержит довольно много информации, но так и не был переведён на русский язык (и украинский тоже)
Даже нет запроса на добавление языка https://www.drupal.org/project/user_guide
Я даже и не знал, что такое есть на drupal.org, пойду создам запрос.
Кто хочет поучаствовать в переводе User Guide, пишите в комментариях к issue:
https://www.drupal.org/node/3048870/
В инструкции к user_guide предлагают использовать freetm.com как бесплатный инструмент для переводов. Я посмотрел его мельком и чё-то как-то фу.
У нас уже есть https://l10n.drupal.ru. Это сервис crowdin.com, о котором я писал в конце марта.
Там есть поддержка gitlab, markdown — это, как я понимаю, может пригодиться при переводе документации.
Я полагаю, что инструмент не так важен, намного важнее ревью и своевременное обновление в соответствии с английским оригиналом
Налетай на таски, с пылу с жару!
https://www.drupal.org/project/user_guide/issues/3049284
Думаю скоро добавят русскую версию User Guide и можно будет выкатывать переводы.
Не мешало бы этот урл задействовать - https://drupal.ru/quickstart
Для начала сделаем категорию «Быстрый старт в Drupal». Когда наберем некоторое количество материалов, которые подходят по этой теме можно будет выделить их в отдельную страницу.
Суть раздела еще и в том, что каждый сможет написать хоть пару абзацев, а вместе это будет что-то стоящее.
Всплакнул от ностальгии) Но так да, что-то такое хорошо бы придумать.
Пока что можно рекомендовать друпалбук для старта.
Рекомендую применять внедрение с помощью оператора, подобного include. Как в старой версии MediaWiki.
Тогда можно будет любой фрагмент текста (и не только - чего угодно) прикручивать к структурам различных документов, а также внедрять непосредственно в любые другие фрагменты документов. При изменении внедренного фрагмента автоматом будет изменено содержимое всех связанных документов. Никакой перелинковки не понадобится.
Дело очень нужное, плюс было бы здорово еще организовать какую нибудь "голосовалку", даже достаточно самыми что ни на есть контрибными модулями,
чтобы можно было не "блуждать" по подобным вопросам, а получать более менее оперативно и более-менее четко сформулированный фидбэк от сообщества: чего ему на самом деле надо.
А что сообществу надо, то и будет наиболее востребованно..
Ваш КО-))
Сделайте ещё раздел с видеоуроками. Можно пособирать туда уже готовый материал.
В целом как раз по темам и можно добавлять и видео, вряд ли кто-то будет против.
Быть может сделают в документации поле, и можно будет фильтровать "материалы с видео"?
Был http://drupal-tv.ru/ у xandeadx
Есть https://drupal.tv
Что-то подобное зачиналось и на dru.io.
https://github.com/dru-io/drupal8-cms-guide
https://github.com/dru-io/drupal8-cms-guide/wiki/Drupal-8-%D0%A7%D1%82%D...
Но как по мне Wiki разметка не удобна для написания статей по программированию, только каких-то базовых вещей.
Я бы поучаствовал в разделе документации. Наверно вряд ли получится строгая документация, кто-то считает что нужно кратко излагать, кто-то что нужно расписывать и снимать видео дополнительно. Если нужно что-то для начала, то может быть перенести все текста с drupalbook.ru?
Дело пойдет быстрее если у документации будет своя kanban доска на trello или еще где-нибудь, где можно быстро предложить тему или взять тему в работу, без потери времени на поиск чего бы добавить в документацию.
Ты же понимаешь, что можешь потерять посещаемость своего сайта? Не отговариваю, просто предупреждаю...
Так то была бы супер клевая база, всегда даю твою ссылку для новичков.
Да я бы с радостью перенес все на drupal.ru, да и забил на свой drupalbook.ru сайт. Я собрался писать статьи на английском, будет стимул продолжить drupalbook.org.
Мое уважение к тебе на порядок выросло
На нашем дев-сервере уже можно потестировать новый раздел «Документация» https://dev.drupal.ru/docs
Раздел «Документация» запущен!
Добавлено отображение подписи участника и атрибуции.
Подпись участника
Авторы материалов в разделе «Документация» будут отображаться под текстом ноды, а не сверху, как в блого-записях. Это сделано по двум причинам:
1. Оригинальное авторство и авторы дополнений
Первый автор принятого материала будет указываться в поле «Авторы». Любой участник может предложить улучшение или дополнение в определенный материал раздела. Авторы значительных дополнений будут также указываться в поле «Авторы». Таким образом будет видно, какие участники вносят вклад в развитие раздела.
2. Промо-подпись
В материалах документации справа от имени автора будет отображаться подпись участника. Настроить текст можно в новом поле «Промо подпись» в профиле участника. Промо-подпись будет отображаться пока только в документации. Возможно, в будущем мы придумаем, где еще будет отображаться промо-подпись.
Пример отображение промо-подписей.
Слева: подпись не установлена участником
Справа: участники добавили промо-подписи
В промо-подписи можно рекламировать себя или свою компанию, если она предоставляет услуги, прямо или косвенно связанные с Drupal (разработка, поддержка, продвижение, аналитика, сервисы и т. п.) Особых правил для промо-подписей еще не выработано, но текст подписей не должен нарушать правила сайта. Думаю, со временем мы добавим в правила пункт, касающийся промо-подписей.
2. Атрибуция
Если материал документации был создан на основе текстов с других сайтов или переведен на русский с иностранных языков, то в поле «Атрибуция» необходимо указать авторство и/или ссылку на оригинальный текст.
Пример отображение атрибуции
Текст документации был создан на основе материалов с сайта xandeadx.ru.
Шикарно! Может банер для бОльшего охвата?
А вот каверзный вопрос: например, хочу написать статью, которую и в блог (возможно очень качественную, на главную страницу сайта чтобы попала в перспективе), но ее можно и в документацию в какой-либо из разделов.
Как быть?
Чуть позже сделаем так, чтобы ноды из документации отображались в блоге участника, в трекере и чтобы их можно было добавлять на главную.