Это руководство по написанию эффективных отчётов об ошибках в Discourse, чтобы максимизировать шансы на их исправление.
Требуемый уровень пользователя: Любой может сообщить об ошибке
Написание качественного отчёта об ошибке необходимо для того, чтобы команда Discourse могла эффективно устранять проблемы. В этом руководстве мы пошагово разберём рекомендации и лучшие практики, которые помогут сделать ваш отчёт ясным, лаконичным и полезным для исправления.
Краткое содержание
В этой документации мы рассмотрим:
- Важность предоставления воспроизводимых шагов и конкретных деталей
- Как описать проблему и ожидаемое поведение
- Лучшие практики для отчётов на разных платформах
- Поддержание подходящего тона в вашем отчёте
- Распространённые ошибки и способы их решения
Шаги для написания эффективного отчёта об ошибке
Приоритет/Серьёзность
Определите срочность исправления ошибки. Хотя всем хочется быстрого решения, наивысший приоритет следует резервировать только для критических проблем, которые существенно влияют на функциональность.
Платформа
Всегда указывайте среду, в которой была обнаружена ошибка. Это включает:
- Тип устройства (настольный компьютер, мобильное устройство, сенсорный экран, планшет)
- Операционную систему и её версию
- Веб-браузер и его версию
По возможности воспроизведите ошибку на нескольких платформах, чтобы подтвердить её наличие.
Описание
Будьте лаконичны. Опишите проблему просто, без лишних деталей. Разделяйте разные проблемы, если их можно сообщить отдельно. Чёткий формат описания включает:
Фактический результат: Что происходит?
Ожидаемый результат: Что должно было произойти?
Избегайте предположений о том, что читатель уже знает. Чётко укажите, что именно должно было быть видно или произойти.
Воспроизводимые шаги
Убедитесь, что ошибку можно воспроизвести последовательно. Напишите пошаговые инструкции, начиная с главной страницы Discourse. Если ошибка возникает случайно, укажите частоту её появления (например, 1 раз из 10 попыток). Для ошибок, связанных с UI/UX, добавьте скриншоты или видео для наглядности.
Тон
Сохраняйте уважительный и вежливый тон. Избегайте использования отчёта об ошибке для выражения раздражения. Любые токсичные высказывания или поведение могут привести к задержке или игнорированию вашего отчёта.
Шаблон
Используйте этот шаблон, чтобы быстро начать новую тему с отчётом об ошибке:
Приоритет/Серьёзность:
Платформа:
Описание:
Воспроизводимые шаги:
Лучшие практики
- Воспроизведение в безопасном режиме: Перед подачей отчёта попробуйте воспроизвести проблему в безопасном режиме Discourse, если подозреваете, что причиной могут быть кастомизации.
- Проверяйте предположения: Отчёты об ошибках часто возникают из-за ложных предположений. Даже в своём отчёте подвергайте сомнению и уточняйте любые свои предположения.
- Будьте подробны: Для трудноуловимых или редких ошибок предоставьте как можно больше деталей. Включите всё, что, по вашему мнению, может быть связано, например, сообщения об ошибках или файлы журналов.
Распространённые проблемы и решения
Проблема: Невозможно последовательно воспроизвести ошибку.
Решение: Задокументируйте среду и условия, при которых возникает ошибка. Отметьте любые закономерности или общие черты.
Проблема: Отсутствие ответа на отчёт об ошибке.
Решение: Убедитесь, что ваш отчёт подробный, но лаконичный и написан в вежливом тоне.
Часто задаваемые вопросы (FAQ)
В: Что делать, если у меня нет времени на подробный отчёт?
О: Всё равно полезно открыть отчёт с имеющейся информацией. Укажите, что вы дополните его деталями позже.
В: Где мне разместить свой отчёт об ошибке?
О: Используйте соответствующую категорию — отчёты об ошибках должны размещаться в категории bug.