documentation-writer

documentation-writer — официальный навык из репозитория GitHub для подготовки технической документации по принципам Diátaxis. Его назначение — помочь автору сначала определить задачу читателя, а затем выбрать подходящий тип документа: tutorial для обучения через практическую последовательность действий, how-to guide для решения конкретной проблемы, reference для точного описания технических деталей или explanation для разъяснения темы и контекста. Такое разделение не является декоративной разметкой: оно помогает не смешивать учебный маршрут, рецепт, справочник и аналитическое объяснение в одном тексте. Рабочий процесс навыка начинается с уточнения. Перед написанием он должен выяснить тип документа, целевую аудиторию, пользовательскую цель и границы темы — что включить и что исключить. После этого навык предлагает подробную структуру с кратким назначением разделов и ожидает подтверждения плана. Только после согласования outline он формирует полный материал в Markdown. Поэтому карточка подходит для команд, которым нужно последовательно превращать технический запрос в документацию с понятной структурой, а не получать непрозрачный черновик без согласования. В основе подхода лежат четыре требования. Текст должен быть ясным, то есть написанным простыми и однозначными формулировками. Он должен быть точным, особенно там, где встречаются команды, API и технические детали. Он должен учитывать цель конкретного читателя, а не просто перечислять сведения. Наконец, он должен сохранять единообразный стиль и терминологию. Эти правила полезны при подготовке tutorial для нового пользователя, how-to для повторяемой операции, API reference для разработчика и explanation для обсуждения архитектурного решения. Навык умеет использовать переданные пользователем Markdown-файлы как контекст, чтобы учитывать уже существующие термины, тон и структуру проекта. При этом исходное описание прямо ограничивает копирование: содержание таких файлов нельзя переносить без явной просьбы. Внешние сайты и дополнительные источники также не должны консультироваться автоматически; для этого пользователь должен предоставить ссылку и отдельно попросить использовать её. Такое ограничение важно для репозиториев, где документация должна оставаться в пределах подтверждённого набора материалов. Практический сценарий выглядит так: сначала автор передаёт тему и имеющиеся файлы, затем отвечает на вопросы о читателе и результате, проверяет предложенную структуру и только после этого принимает Markdown-документ. Навык полезен для проектной документации, руководств по эксплуатации, справочников интерфейсов и объяснений принятых решений. Ограничение карточки — необходимость диалога и согласования плана: она не заменяет проверку фактов, запуск команд или ревью готового текста. Финальный документ всё равно нужно сверить с реальным продуктом и обновить, если меняются API или процессы.