writing-guidelines

Writing Guidelines — это skill Vercel для проверки документации и прозы по набору редакционных правил. Он предназначен для ситуаций, когда нужно проверить стиль текста, голос продукта, тон документации или соответствие страницы writing handbook. Skill получает путь к файлу или pattern, читает переданные материалы и выдаёт компактные находки в формате file:line. Когда путь не передан, он не имитирует проверку проекта, а просит указать файлы или шаблон. Результат должен оставаться кратким, но содержать достаточно контекста для исправления. Перед каждым ревью skill предписывает получить свежую версию Writing Guidelines с отдельного исходного URL. Это важно, потому что набор правил может измениться после публикации карточки. После загрузки правил агент сопоставляет с ними каждый переданный файл. Сам skill не заменяет исходный handbook и не обещает, что найденные проблемы исправлены автоматически: его результатом является ревью с координатами строк. В проверяемый контент входят план и тип страницы, цель, аудитория, заголовок и структура. Правила предлагают объявлять content type: Tutorial, How-to, Reference, Conceptual, Troubleshooting или Landing. Заголовок должен отражать задачу читателя, а цель формулироваться глаголом, который можно проверить. Страница должна выполнять одну основную работу, а разделы должны начинаться с понятного краткого объяснения. Для многошаговых действий источник предусматривает видимую структуру шагов и рекомендует отделять обзор от последовательных инструкций. Отдельный блок посвящён голосу и читаемости. Skill проверяет активный залог, прямое обращение, повелительные формулировки в шагах, настоящее время и предложения, которые читатель понимает с первого прочтения. Он отмечает рекламные filler-слова, расплывчатые количественные утверждения, риторические вопросы, пассивные конструкции и шаблонные переходы. Заголовки должны использовать sentence case, термины и акронимы нужно объяснять при первом появлении, а длинные абзацы следует разделять по смыслу. Важна не механическая длина текста, а то, помогает ли каждая деталь выполнить задачу страницы. При ревью списков и кода skill смотрит на структуру, форматирование и объяснимость. Три и более однородных пункта в абзаце предлагается вынести в маркированный или нумерованный список. Блоки кода должны иметь языковую метку, оставаться короткими и сопровождаться пояснением действия. Правила отдельно проверяют placeholders, единицы измерения, типографику, ссылки, подписи интерфейса и доступность примеров. В техническом тексте нужно сохранять актуальные идентификаторы моделей и не использовать вымышленные значения, которые выглядят как реальные credentials. Skill также покрывает качество документации после редактуры: findability, accuracy, relevance, clarity, completeness и readability. Для примеров важны запускаемость и соответствие текущему интерфейсу. Для обучающих материалов нужны prerequisites, quickstart, понятные шаги и ограничения; для reference-страниц требуется нейтральная, цитируемая организация по поверхности продукта. Финальная проверка остаётся человеческой: карточка не является доказательством, что код запускается или что страница полностью соответствует продукту без preview и проверки. Источник описывает Writing Guidelines как ревью-инструмент, а не редактор, генератор контента или средство публикации. Он не должен скрыто менять файлы, подменять план страницы и делать выводы по одному заголовку. Полезный сценарий таков: выбрать файлы, загрузить свежие правила, проверить все относящиеся к ним требования, сгруппировать находки по файлу и строке, а затем отдельно принять решение об исправлениях и повторной проверке.