Шаблон улучшения документации
Проблема документации¶
Тип документации - [ ] Руководство пользователя - [ ] Руководство разработчика - [ ] Документация API - [ ] Руководящие принципы участия - [ ] README - [ ] Комментарии кода - [ ] Документация архитектуры - [ ] Инструкции по настройке - [ ] Другое: ___________
Конкретный документ/Раздел Пожалуйста, укажите, какой документ или раздел нуждается в улучшении: - Путь к файлу: [например, docs/user-guide/getting-started.md] - Раздел: [например, "Инструкции по установке"] - Номера строк (если применимо): [например, строки 45-60]
Описание проблемы¶
Что не так? Четко опишите проблему с текущей документацией: - [ ] Информация устарела - [ ] Информация неверна - [ ] Информация отсутствует - [ ] Информация неясна/запутанна - [ ] Плохая организация/структура - [ ] Сломанные ссылки - [ ] Отсутствующие примеры кода - [ ] Несогласованное форматирование - [ ] Проблемы доступности - [ ] Другое: ___________
Подробное описание Предоставьте конкретные детали о том, что нужно улучшить.
Предлагаемое решение¶
Предлагаемые изменения Опишите, какие изменения, по вашему мнению, следует внести:
Улучшения контента - Какую информацию следует добавить? - Что следует уточнить или переписать? - Какие примеры были бы полезны?
Структурные улучшения - Как следует реорганизовать контент? - Какие разделы следует добавить или удалить? - Как можно улучшить навигацию?
Целевая аудитория¶
Кто выиграет от этого улучшения? - [ ] Новые пользователи - [ ] Опытные пользователи - [ ] Новые разработчики - [ ] Опытные разработчики - [ ] Исследователи - [ ] Участники - [ ] Все аудитории
Влияние на пользовательский опыт Как это улучшение поможет пользователям?
Дополнительный контекст¶
Текущее поведение Что происходит, когда пользователи следуют текущей документации?
Ожидаемое поведение Что должно происходить с улучшенной документацией?
Связанная документация Есть ли другие документы, которые следует обновить согласованно?
Внешние ссылки Любые внешние ресурсы, которые могли бы помочь улучшить документацию?
Детали реализации¶
Тип контента - [ ] Текстовый контент - [ ] Примеры кода - [ ] Скриншоты/Изображения - [ ] Диаграммы - [ ] Видео - [ ] Интерактивные элементы
Область изменений - [ ] Незначительные правки текста - [ ] Переписывание раздела - [ ] Новый раздел/страница - [ ] Структурная реорганизация - [ ] Обновления нескольких документов
Технические требования - [ ] Нужны новые скриншоты - [ ] Примеры кода нуждаются в тестировании - [ ] Ссылки нуждаются в проверке - [ ] Диаграммы нуждаются в создании/обновлении - [ ] Нужны обновления переводов
Приоритет и влияние¶
Уровень приоритета - [ ] Критический - Блокирует пользователей от выполнения задач - [ ] Высокий - Вызывает значительную путаницу - [ ] Средний - Заметное улучшение необходимо - [ ] Низкий - Незначительное улучшение
Влияние на пользователей - [ ] Затрагивает всех пользователей - [ ] Затрагивает в основном новых пользователей - [ ] Затрагивает в основном разработчиков - [ ] Затрагивает конкретную группу пользователей: ___________
Критерии приемки¶
Определение готовности - [ ] Контент точен и актуален - [ ] Информация ясна и хорошо организована - [ ] Примеры кода работают правильно - [ ] Ссылки функциональны - [ ] Скриншоты актуальны - [ ] Контент следует руководству по стилю - [ ] Соблюдены руководящие принципы доступности - [ ] Связанные документы обновлены
Чек-лист рецензирования - [ ] Техническая точность проверена - [ ] Ясность контента подтверждена - [ ] Примеры протестированы - [ ] Ссылки проверены - [ ] Форматирование согласовано - [ ] Грамматика и орфография правильны
Информация о волонтере¶
Можете ли вы помочь реализовать это улучшение? - [ ] Да, я могу написать контент - [ ] Да, я могу предоставить техническое рецензирование - [ ] Да, я могу создать скриншоты/диаграммы - [ ] Да, я могу протестировать документацию - [ ] Нет, но я могу предоставить обратную связь - [ ] Нет, я просто сообщаю о проблеме
Временные рамки Если вы волонтер, когда вы могли бы работать над этим?
Чек-лист перед отправкой: - [ ] Я искал существующие проблемы документации - [ ] Я четко определил проблему - [ ] Я предоставил конкретные предложения - [ ] Я рассмотрел целевую аудиторию - [ ] Я проверил связанную документацию