Fowel

Что такое Fowel?

Fowel — GitHub App, которая проверяет изменения документации в pull requests. Она автоматически оставляет inline-комментарии и обзорный отзыв, чтобы выявить проблемы документации — такие как неверная или устаревшая информация, нехватка контекста, неясное изложение и сломанные примеры — до мержа изменений.

Основная цель Fowel — добавить автоматизированную проверку качества документации к code review. Она фокусируется на файлах документации (включая Markdown и MDX) и оценивает их по нескольким факторам качества, чтобы разработчики и ревьюеры могли решать проблемы раньше в workflow.

Ключевые возможности

• GitHub App для проверок документации по PR: Fowel устанавливается в GitHub-репозитории и запускает проверки при включении изменений документации в pull request.
• Автоматическое обнаружение файлов документации: Она определяет Markdown, MDX и другие типы doc-файлов при их изменении в PR, так что ревьюерам не нужно вручную выбирать, что проверять.
• Inline-комментарии плюс обзорный отзыв: Fowel оставляет детальный inline-feedback и общий отзыв в pull request, чтобы проблемы были видны во время ревью.
• Аудит документации по нескольким факторам качества: Проверяет точность контента, путь разработчика/onboarding flow, структуру и информационную архитектуру, кодовые примеры (включая работоспособность и обработку ошибок), ясность и стиль, полноту.
• Поддержка автоматических и ручных проверок: Продукт включает автоматизированные запуски ревью и возможность ручного триггера.

Как использовать Fowel

1. Установите GitHub App: Добавьте Fowel в репозиторий через one-click install. На сайте указано, что не требуются конфигурационные файлы, изменения CI или скрипты настройки.
2. Откройте pull request с изменениями документации: Запушьте обновления документации в ветку и откройте PR. Fowel автоматически обнаружит файлы документации.
3. Просмотрите отзывы Fowel в PR: Изучите inline-комментарии и summary от Fowel. Исправьте проблемы (например, устаревшие утверждения, отсутствие документации ошибок или сломанные кодовые примеры) и обновите PR при необходимости.

Сценарии использования

• Выявление устаревших процедур до мержа: При обновлении API-доков или гайдов Fowel отметит противоречия и неверные процедуры, которые code review может пропустить.
• Улучшение onboarding flow для “time to first success”: Fowel оценивает аспекты пути разработчика в документации, помогая обеспечить первый API-вызов без оттока из-за отсутствия контекста настройки.
• Проверка качества reference-документации: Для эндпоинтов и страниц API reference Fowel проверяет навигацию, структуру, naming, кросс-линки и полноту документации для поиска конкретных деталей.
• Обнаружение сломанных или вводящих в заблуждение кодовых примеров: Если примеры устарели или без обработки ошибок, Fowel проверяет работоспособность и синтаксис, чтобы разработчики не копипастили неработающие сниппеты.
• Снижение нагрузки на поддержку из-за отсутствия docs по ошибкам/контексту: Для изменений с параметрами, заметками об аутентификации или error responses Fowel проверяет наличие и достаточную ясность информации, чтобы избежать “угадывания” и повторных вопросов.

FAQ

Fowel проверяет только Markdown-файлы?
Нет. На странице указано, что она автоматически обнаруживает Markdown, MDX и другие doc-файлы при их включении в pull request.

Где отображаются результаты?
Fowel оставляет inline-комментарии и обзорный отзыв в pull request.

Ревью только автоматические или можно вручную?
Поддерживаются оба: автоматические ревью и ручные триггеры.

Что проверяет Fowel в документации?
Проводит аудит по нескольким факторам качества, включая точность контента, путь разработчика, структуру и информационную архитектуру, кодовые примеры, ясность и стиль, полноту.

Fowel заменяет code review?
Сайт представляет Fowel как дополнительную проверку качества документации в workflow pull request; она дополняет code review, фокусируясь на проблемах документации, которые ревьюеры кода могут не заметить.

Альтернативы

• Внутренний процесс проверки документации (чек-листы или ревью от коллег): Команды могут полагаться на человеческих ревьюеров с чек-листами качества. По сравнению с Fowel это менее автоматизировано и обычно выявляет проблемы позже.
• Статический линтинг документации/линтеры: Инструменты линтинга документации могут обеспечивать соблюдение правил форматирования или базовой корректности. Они обычно не предоставляют многофакторный аудит документации и контекстный встроенный ревью, как описано для Fowel.
• Платформы для документации API с встроенной валидацией: Инструменты для генерации документации API могут снижать расхождение документации для определённых источников, но они могут не проверять качество текста, поток онбординга, структуру и работоспособность примеров так, как описано для Fowel.
• Общая автоматизация ревью pull request: Широкая CI или автоматизация PR может отмечать сломанные сборки и тесты, но она не адаптирована специально под точность, ясность и полноту документации.