Новый плагин документации в разработке

Новости и события Объявления
,
1

Недавно мы выпустили новый плагин документации для тестирования и сбора отзывов. Этот плагин разработан для улучшения навигации и доступности документации, размещённой на Discourse, обеспечивая более удобный и дружелюбный опыт для всех пользователей. Обратите внимание: плагин всё ещё находится в разработке.

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

:boom: Новый плагин в действии

Плагин в настоящее время активен и обеспечивает работу документации на нашей официальной документации Discourse. Мы приглашаем вас изучить его функции и поделиться своим опытом. Ваши отзывы бесценны для того, чтобы мы могли доработать и улучшить плагин.

Основные функции нового плагина включают:

  • Настройки для определения категорий, используемых для документации
  • Новая боковая панель документации, заполняемая индексами тем в каждой категории
  • Два новых отчёта для поддержания целостности и точности индексов тем

С добавлением новых функций по мере непрерывного улучшения доступных возможностей.

Новый плагин уже можно скачать и установить: Discourse Doc Categories

:electric_plug: Переход с плагина Discourse Docs

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

Обратите внимание, что новый плагин всё ещё находится на экспериментальной стадии. Хотя мы стремимся обеспечить бесшовный опыт, могут потребоваться дальнейшие улучшения в некоторых областях. Ваши конструктивные отзывы будут крайне важны для его успеха.

:speaking_head: Поделитесь своим мнением

Мы будем благодарны за ваши мысли, опыт и отзывы. Не стесняйтесь делиться своими впечатлениями и любыми наблюдениями, полученными при использовании нового плагина документации — будь то через навигацию по документации на Meta или установку плагина на вашем собственном сайте.

Наша цель — создать лучший опыт работы с документацией для всего сообщества Discourse, поэтому все отзывы приветствуются!

Полная информация о плагине доступна здесь:

13 лайков
2

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

Кажется, это также отлично подойдёт для использования Discourse в качестве системы управления обучением (LMS). Для этого было бы полезно иметь возможность переключать категорию, которая является категорией документации, хотя есть большая вероятность, что достаточно просто использовать права доступа, чтобы предоставить пользователям доступ к определённым категориям, и всё заработает «из коробки».

8 лайков
3

Отлично подмечена ссылка на URL — я только что отправил PR, чтобы добавить её.

Звучит как интересный вариант использования, и я вижу, как это могло бы работать довольно эффективно!

6 лайков
4

Это фантастическое улучшение по сравнению с оригинальным плагином Docs/база знаний. На данный момент выглядит очень удобным для пользователя.

Тестирование на Meta — это огромный плюс, так как здесь категории документации было трудно найти ранее.

5 лайков
5

Неужели я могу спросить о сроках? То есть, когда этот плагин будет считаться менее экспериментальным и перейдет в стадию бета-версии, а возможно, даже раннего кандидата на релиз? Я понимаю, как сложно предсказать будущее, поэтому буду рад любой приблизительной оценке, насколько бы неточной она ни была. :wink:

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

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

Категория «Документация» на meta.discourse.org теперь ощущается как полноценный структурированный сайт документации, а не просто набор случайных тем форума, которые случайно объединены в одну категорию и описывают работу Discourse.

Так что продолжайте в том же духе. Спасибо!

1 лайк
7

Мне это очень нравится! Документация и обсуждения отлично дополняют друг друга.

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

8

Я думаю, что текущий этап можно охарактеризовать так: «красота (или её отсутствие) в глазах смотрящего».

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

Сказав всё это, мы будем очень рады получить вашу обратную связь, если вы попробуете его и проверите его работу.

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

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

4 лайка
9

Насчёт этого: если вы находитесь в категории документации и закрываете окно чата, не занимающее весь экран, навигация по документации также «закрывается», и снова отображается обычная панель навигации. Хотя проблема воспроизводится на meta, я также заметил, что при нажатии на пузырёк чата (в правом верхнем углу заголовка) навигация по документации тоже закрывается. Надеюсь, это поможет!

3 лайка
11

Спасибо за сообщение об этой проблеме — я смог воспроизвести её, поэтому зафиксировал. Мы включим это в предстоящие работы по разработке здесь.

3 лайка
13

Это напомнило мне об одной вещи в проекте Discourse, которая меня как пользователя не совсем устраивает. А именно: проект не использует полноценный публичный трекер задач для багов и планирования.

Например, когда я прочитал ответ Хью, мой внутренний менеджер проекта сразу задал вопрос: где, где это было зафиксировано?. Знаю, мой внутренний менеджер — любопытное создание, не так ли? :slight_smile:

Предполагаю, что использование meta.discourse.org в качестве трекера задач даёт проекту возможность «собачьего кормления» (dogfooding) с помощью Discourse. У всех остальных трекеров задач тоже есть свои недостатки, поэтому выбирать один из них — боль. Но для меня Discourse, хотя и отлично подходит как форум для вопросов и обсуждений, очень слаб в роли трекера задач. Для этой цели ему не хватает эффективной категоризации, информации о затронутых и целевых версиях, номеров задач, приоритизации, эффективных средств фильтрации задач по статусу, возрасту, приоритету, продукту или компонентам, а также хорошего способа представить дорожную карту для функции или продукта в целом, среди прочего.

Ну, я отвлекся. И я ещё не внёс ни строчки кода, не отправил отчёт об ошибке или запрос на новую функцию, так что кто я такой, чтобы жаловаться. :wink:

Так что ещё раз спасибо всем за превосходность Discourse. И простите за полупроповедь.

И по теме: здорово слышать, что категории документации Discourse, хотя ещё и не доведены до совершенства, считаются архитектурно стабильными. Проверю, смогу ли я установить их на свой размещённый экземпляр Discourse, и если получится, вернусь с обратной связью. Спасибо!

6 лайков
14

Я забыл ответить здесь. Спасибо за напоминание.

Я понимаю, что Wiki может подходить под разные категории, например community support dev, и лучше отображать данные на основе интересов пользователей по темам.

В то же время, отображение этих вики-страниц, организованных в документации (ссылка в боковом меню вики), звучит отлично.

1 лайк
15

Мы используем Discourse как трекер задач. Точнее — я пытаюсь заставить свою команду использовать Discourse в качестве трекера задач :slight_smile: А также вики, форума и документации… Я подозреваю, что у команды CDCK есть другой «секретный» сайт на Discourse, где они отслеживают свои задачи internally, используя какие-то интересные плагины, о которых никто не знает…

Неважно, насколько хорош трекер задач здесь, сообщество нельзя сравнить ни с чем другим, что я знаю. В конце концов, именно люди разрабатывают программное обеспечение, а не технологии, стоящие за ним. И они просто великолепны! :metal:

Мне также очень нравится плагин для документации. :heart:

Теперь, после всей этой похвалы, возможно ли одобрить мой PR? :smiley:

5 лайков
16

Ты видел ответ Герхарда на этот PR?

3 лайка
17

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

В основном мы следуем соглашениям: например, создаём категорию для «задач» и используем стандартный набор из нескольких тегов для приоритизации по принципу «сейчас/далее/позже», а также плагин assign для уточнения ответственности.

Это позволяет работать компоненту темы Kanban, но не все используют этот вид.

Процесс довольно гибкий, это не жёстко настроенный трекер задач, но для нас он работает хорошо.

Когда-нибудь я мог бы поделиться более подробной информацией…

6 лайков
18

Нет! Это моя ошибка. Исправлено. Спасибо за уведомление.

3 лайка