Это руководство содержит инструкции по написанию эффективных инструкций «как сделать» для Discourse. Оно охватывает такие ключевые аспекты, как структура и стиль, учёт аудитории и поддержка материалов.
Требуемый уровень пользователя: написать новую инструкцию «как сделать» может любой пользователь
Написание эффективных инструкций «как сделать» имеет решающее значение для помощи пользователям, модераторам, администраторам и системным администраторам в выполнении различных задач в Discourse. Это руководство поможет вам создавать понятные и полезные инструкции для сообщества.
Краткое содержание
В этом документе вы узнаете:
- Почему важно писать инструкции «как сделать»
- Какую информацию следует включать
- Руководящие принципы по структуре и стилю
- Где публиковать такие темы
- Как поддерживать их актуальность после публикации
Зачем писать инструкцию «как сделать»?
Бывало ли у вас так, что вам нужно было выполнить задачу, но вы не могли вспомнить, как это сделать? Написание документа «как сделать» — отличный способ задокументировать процессы в Discourse. Если вы испытываете трудности с определённым процессом, скорее всего, это же испытывают и другие. Документирование этого помогает всем.
Узнайте больше о том, чем инструкция «как сделать» отличается от других типов документации, таких как учебные пособия или справочные руководства, в этом руководстве от Divio.
Написание или проверка инструкции «как сделать» — отличный способ начать делиться своими знаниями о Discourse с сообществом. Другие способы внести свой вклад можно найти в руководстве как внести вклад в Discourse.
Какую информацию следует включать?
Инструкция «как сделать» должна быть пошаговым руководством, ведущим пользователя к конкретному результату. Например, инструкция под названием «Настройка HTTPS для Discourse» должна содержать инструкции по настройке HTTPS.
Ключевые моменты, о которых следует помнить при написании инструкции «как сделать»:
- Придерживайтесь темы и будьте понятны
- Избегайте ненужной информации
- Будьте краткими, но информативными
- Объясните, почему достижение конечного результата полезно
Учитывайте свою аудиторию
У инструкций «как сделать» для Discourse есть разные аудитории, каждая из которых требует разного уровня детализации. Используйте категории документации как ориентир для определения целевой аудитории вашего руководства:
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
Понимайте уровень технических навыков вашей аудитории и адаптируйте своё руководство соответствующим образом. Несколько советов:
- Избегайте шагов, которые аудитория не может выполнить (например, клиенты хостинга обычно не имеют доступа к командам консоли)
- Делайте инструкции понятными и избегайте сложного технического языка для нетехнических пользователей
- Не добавляйте справочную информацию, которую ваша аудитория уже должна знать
Структура и стиль
Руководство по стилю документации охватывает всё, что вам нужно знать о том, как структурировать и оформлять инструкции «как сделать» (и всю остальную документацию Discourse):
Публикация руководства
Публикуйте руководства в подкатегории родительской категории Documentation и помечайте их тегом how-to. Все руководства требуют одобрения команды Discourse, которое автоматически обрабатывается через процесс модерации. Руководство по стилю более подробно описывает каждую категорию, чтобы помочь вам решить, где следует разместить ваше руководство.
Поддержка вашего руководства
После публикации инструкции «как сделать» следите за её актуальностью. Вот как вы можете помочь её поддерживать:
- Следите за ответами — учитывайте отзывы сообщества в руководстве.
- Проверяйте руководство самостоятельно — периодически проходите по руководству, чтобы убедиться в его актуальности.
- Исправляйте отсутствующую или неверную информацию — если у вас уровень доверия 2 или выше, отредактируйте первый пост инструкции.
- Отмечайте темы для помощи — если вы не можете внести правку, отметьте пост тегом «Что-то ещё» и объясните, что необходимо.
В большинстве случаев официальные инструкции «как сделать» будут иметь удалённые комментарии через месяц, чтобы сохранить фокус на самом руководстве.
Спасибо за улучшение документации сообщества Discourse! Если вы застряли, не стесняйтесь просить о помощи. Лучший способ начать — это вносить свой вклад и учиться по ходу дела.