Разработка нового раздела «Документация»

Аватар пользователя madt madt 16 апреля в 16:24
3

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

Помимо грандиозных масштабов задачи возникает и множество вопросов:

  • Какие темы стоит затронуть в первую очередь?
  • Что наиболее интересно начинающим и продвинутым друпалерам?
  • Каким должен быть формат документации: краткие заметки или лонгрид?
  • Не «утонет» ли статья в трекере через пару недель?
  • Как структурировать информацию?
  • И многие другие.

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

Мы решили добавить на сайт новый раздел, который будет называться «Документация». Ниже будут представлены предварительные результаты обсуждения в репозитории проекта.

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

Функциональность раздела «Документация»

  • Новый словарь категорий документации, пополняемый редакцией сайта на основе данных Яндекс.Метрики и предложений участников сообщества
  • Новый тип материала «Документация»
  • Новая страница /docs для отображения категорий, опубликованных материалов и «рекомендуемых» тем для документации
  • Ранее опубликованные интересные и актуальные статьи будут конвертированы в новый тип материала
  • Любой зарегистрированный пользователь сможет добавить материал в раздел
  • Любой зарегистрированный пользователь сможет добавить комментарий к материалам
  • Будет создана новая роль «Модератор документации» с правами на изменение материалов в разделе
  • Новые материалы, созданные участниками будут сохраняться в неопубликованном виде и не будут отображаться в списке
  • Одобренные материалы будут публиковаться и выводиться в разделе в виде ссылок
  • Для некоторых категорий будут созданы «рекомендуемые темы», которые будут отображаться в виде текста под списком опубликованных материалов
  • При наведении на название категории будет появляться иконка добавления материала в категорию. Клик на иконку у категории откроет форму создания ноды с заполненным полем категории документации.
  • При наведении на предложенную тему будет появляться иконка добавления материала. Клик на иконку у предложенной темы откроет форму создания ноды с заполненным заголовком и полем категории документации

Несколько скриншотов

Главная страница раздела «Документация»

Главная страница раздела «Документация»

Пояснения к главной странице раздела «Документация»

Пояснения к главной странице раздела «Документация»

После клика на иконку у категории

После клика на иконку у категории

После клика на иконку у предложенной темы

После клика на иконку у предложенной темы


Друзья, нам важно узнать ваше мнение о создаваемом разделе! Напишите, пожалуйста, ваши мысли, идеи и вопросы.

Лучший ответ

Аватар пользователя madt madt 6 мая в 14:48
2

Раздел «Документация» запущен!

Добавлено отображение подписи участника и атрибуции.

Подпись участника

Авторы материалов в разделе «Документация» будут отображаться под текстом ноды, а не сверху, как в блого-записях. Это сделано по двум причинам:

1. Оригинальное авторство и авторы дополнений

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

2. Промо-подпись

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

Пример отображение промо-подписей.
Слева: подпись не установлена участником
Справа: участники добавили промо-подписи

Авторы документации

В промо-подписи можно рекламировать себя или свою компанию, если она предоставляет услуги, прямо или косвенно связанные с Drupal (разработка, поддержка, продвижение, аналитика, сервисы и т. п.) Особых правил для промо-подписей еще не выработано, но текст подписей не должен нарушать правила сайта. Думаю, со временем мы добавим в правила пункт, касающийся промо-подписей.

2. Атрибуция

Если материал документации был создан на основе текстов с других сайтов или переведен на русский с иностранных языков, то в поле «Атрибуция» необходимо указать авторство и/или ссылку на оригинальный текст.

Пример отображение атрибуции
Текст документации был создан на основе материалов с сайта xandeadx.ru.

Атрибуция текста

Комментарии

Аватар пользователя andypost@drupal.org andypost@drupal.org 16 апреля в 17:19
4

Также напомню о https://www.drupal.org/docs/user_guide/en/index.html
который содержит довольно много информации, но так и не был переведён на русский язык (и украинский тоже)
Даже нет запроса на добавление языка https://www.drupal.org/project/user_guide

Аватар пользователя madt madt 18 апреля в 9:35

В инструкции к user_guide предлагают использовать freetm.com как бесплатный инструмент для переводов. Я посмотрел его мельком и чё-то как-то фу.

У нас уже есть https://l10n.drupal.ru. Это сервис crowdin.com, о котором я писал в конце марта.

Там есть поддержка gitlab, markdown — это, как я понимаю, может пригодиться при переводе документации.

Аватар пользователя andypost@drupal.org andypost@drupal.org 19 апреля в 0:35

Я полагаю, что инструмент не так важен, намного важнее ревью и своевременное обновление в соответствии с английским оригиналом

Аватар пользователя madt madt 16 апреля в 17:48

Для начала сделаем категорию «Быстрый старт в Drupal». Когда наберем некоторое количество материалов, которые подходят по этой теме можно будет выделить их в отдельную страницу.

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

Аватар пользователя P.Selfin@drupal.org P.Selfin@drupal.org 17 апреля в 12:38

Всплакнул от ностальгии) Но так да, что-то такое хорошо бы придумать.
Пока что можно рекомендовать друпалбук для старта.

Аватар пользователя sudo sudo 16 апреля в 19:48

Рекомендую применять внедрение с помощью оператора, подобного include. Как в старой версии MediaWiki.
Тогда можно будет любой фрагмент текста (и не только - чего угодно) прикручивать к структурам различных документов, а также внедрять непосредственно в любые другие фрагменты документов. При изменении внедренного фрагмента автоматом будет изменено содержимое всех связанных документов. Никакой перелинковки не понадобится.

Аватар пользователя Orion76 Orion76 18 апреля в 9:36
madt wrote:
  • Какие темы стоит затронуть в первую очередь?
  • Что наиболее интересно начинающим и продвинутым друпалерам?
  • Каким должен быть формат документации: краткие заметки или лонгрид?
  • Не «утонет» ли статья в трекере через пару недель?
  • Как структурировать информацию?
  • И многие другие.

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

А что сообществу надо, то и будет наиболее востребованно..
Ваш КО-))

Аватар пользователя gun_dose gun_dose 17 апреля в 10:05
2

Сделайте ещё раздел с видеоуроками. Можно пособирать туда уже готовый материал.

Аватар пользователя P.Selfin@drupal.org P.Selfin@drupal.org 17 апреля в 12:36

В целом как раз по темам и можно добавлять и видео, вряд ли кто-то будет против.
Быть может сделают в документации поле, и можно будет фильтровать "материалы с видео"?

Аватар пользователя levmyshkin levmyshkin 17 апреля в 18:29
3

Что-то подобное зачиналось и на 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 или еще где-нибудь, где можно быстро предложить тему или взять тему в работу, без потери времени на поиск чего бы добавить в документацию.

Аватар пользователя P.Selfin@drupal.org P.Selfin@drupal.org 18 апреля в 18:03

Если нужно что-то для начала, то может быть перенести все текста с drupalbook.ru?

Ты же понимаешь, что можешь потерять посещаемость своего сайта? Не отговариваю, просто предупреждаю...
Так то была бы супер клевая база, всегда даю твою ссылку для новичков.

Аватар пользователя levmyshkin levmyshkin 18 апреля в 18:51
3

Да я бы с радостью перенес все на drupal.ru, да и забил на свой drupalbook.ru сайт. Я собрался писать статьи на английском, будет стимул продолжить drupalbook.org.

Аватар пользователя madt madt 6 мая в 14:48
2

Раздел «Документация» запущен!

Добавлено отображение подписи участника и атрибуции.

Подпись участника

Авторы материалов в разделе «Документация» будут отображаться под текстом ноды, а не сверху, как в блого-записях. Это сделано по двум причинам:

1. Оригинальное авторство и авторы дополнений

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

2. Промо-подпись

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

Пример отображение промо-подписей.
Слева: подпись не установлена участником
Справа: участники добавили промо-подписи

Авторы документации

В промо-подписи можно рекламировать себя или свою компанию, если она предоставляет услуги, прямо или косвенно связанные с Drupal (разработка, поддержка, продвижение, аналитика, сервисы и т. п.) Особых правил для промо-подписей еще не выработано, но текст подписей не должен нарушать правила сайта. Думаю, со временем мы добавим в правила пункт, касающийся промо-подписей.

2. Атрибуция

Если материал документации был создан на основе текстов с других сайтов или переведен на русский с иностранных языков, то в поле «Атрибуция» необходимо указать авторство и/или ссылку на оригинальный текст.

Пример отображение атрибуции
Текст документации был создан на основе материалов с сайта xandeadx.ru.

Атрибуция текста

Аватар пользователя P.Selfin@drupal.org P.Selfin@drupal.org 6 мая в 16:48

А вот каверзный вопрос: например, хочу написать статью, которую и в блог (возможно очень качественную, на главную страницу сайта чтобы попала в перспективе), но ее можно и в документацию в какой-либо из разделов.
Как быть?

Аватар пользователя madt madt 6 мая в 17:13

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