Недавно мы приложили усилия к улучшению нашей документации здесь, на meta, с акцентом на такую категоризацию, чтобы разные пользователи могли находить темы, актуальные для них, и игнорировать нерелевантные.
Мы стремимся разместить всю документацию в одной из следующих категорий:
- #documentation:users — общие вопросы использования
- #documentation:moderators — модерация сообщества
- #documentation:theme-developers — разработка тем и компонентов тем
- #documentation:admins — администрирование сайта Discourse
- #documentation:devs — разработка функций Discourse, плагинов и интеграций
- #documentation:sysadmin — администрирование самохостинговой системы
Мы планируем удалить категории #documentation:faq и #documentation:tips-and-tricks в конце этого месяца (но уже начали помечать некоторые темы в новых категориях тегом #tips-and-tricks).
Также мы намерены помечать документацию одним из классифицирующих тегов, заимствованных из Divio, согласно этому предыдущему посту:
Не всегда всё идеально вписывается. В некоторых случаях мы разделяем темы, а в других просто используем тег или категорию, которые лучше всего подходят в текущем состоянии.
Вот некоторые типичные изменения, которые мы уже внесли в отдельные темы (мы сейчас на полпути к завершению):
- Перенос тем из #documentation:admins в #documentation:sysadmin, если они требуют доступа к консоли.
- Разделение тем из #documentation:faq на темы для #documentation:admins и темы для #documentation:users.
- Перенос тем из #documentation:devs в #documentation:theme-developers, если они касаются разработки тем или компонентов тем.
- Обновление заголовков тем для большей согласованности:
- Использование повелительного наклонения в заголовках тем (и удаление фразы «как сделать» из заголовка).
- Использование обычного регистра в предложениях.
- Форматирование контента с заголовками, начинающимися с H2.
(Кстати: мы также включили оглавление для всех тем документации.)
В некоторых случаях мы вносим изменения и в сам контент, но глубокое погружение не является нашей первоочередной задачей. На следующем этапе мы хотели бы сделать следующее:
- Включить контент из ответов в саму документацию.
- Удалить все ответы.
- Настроить темы для автоматического удаления ответов через 1 или 2 месяца.
Далее мы предоставим обновлённые рекомендации по внесению новых документов и поддержанию существующих, а также обновим следующие темы:
Возможно, нам стоит преобразовать больше документов в вики или найти новых ответственных за документы, если они поддерживаются кем-то другим, кроме автора оригинального поста, например.
Также мы считаем, что здесь есть возможность создать отдельные пространства для демонстрации и обсуждения («покажи и расскажи») в духе части контента, который ранее находился в #documentation:tips-and-tricks. Выделение отдельных пространств для таких тем вне документации может дать больше возможностей для обсуждения их среди коллег. Но, аналогично тому, что мы делаем сейчас с документацией, возможно, было бы полезно создать отдельные пространства для системных администраторов, администраторов и разработчиков для таких обсуждений. Что вы думаете по этому поводу?