Наверняка с вами такое было: документация к API выглядит полной, эндпоинты перечислены, параметры описаны, а вы всё равно тратите час в Swagger и мессенджере, пытаясь понять, когда вызывать эндпоинт и что его ответ значит для вашей задачи. Документация есть. Ответа в ней нет.
Этот разрыв между «задокументировано» и «понятно» — и есть работа технического писателя. Не человека, который переформатирует заметки инженеров, а того, кто превращает сложный продукт в текст, позволяющий другому человеку действовать, никого не спрашивая. Продуктовая документация, справочники по API, стандарты, руководства по стилю — всё это служит одной цели: читателю не нужно возвращаться к автору с вопросами.
Ниже — как это работает на практике, где ломается и как этому научиться.
Одна задача, разобранная честно
Возьмём конкретную работу: вам нужно задокументировать новый вебхук-эндпоинт POST /v2/orders/status до релиза. Вот как через неё проходит опытный писатель и что идёт не так, если пропустить шаг.
1. Выясните, кто это читает и зачем. Эндпоинт используют интеграторы, которые делают витрины магазинов. Им не важна внутренняя архитектура; им важны три вещи: когда срабатывает событие, какие поля приходят и что делать, если доставка не удалась. Самая частая ошибка новичка — писать для продакт-менеджера, который поставил задачу. В результате: три абзаца о назначении модуля и ни слова о повторных попытках.
2. Получите факты от инженера, а не из кода. Чтение исходников даёт форму, а не семантику. Что значит status: "pending" через 24 часа? Он когда-нибудь станет "failed" или будет висеть вечно? Инженер знает. Ваша задача — задать вопрос, на который есть точный ответ, а не «расскажи мне про вебхук». Полезный формат: «Если я отправлю это дважды, что вернёт второй запрос?» Этот один вопрос вскрывает историю с идемпотентностью.
3. Напишите справочник до руководства. Справочник — это контракт: поля, типы, обязательные/необязательные, пример полезной нагрузки, коды ошибок. Каждое поле получает однострочное описание того, что оно значит для интегратора, а не того, чем оно является в базе данных. Частая ошибка: пример JSON набран вручную и не соответствует схеме — читатель копирует его, получает 400 и перестаёт доверять всему документу.
4. Напишите поверх руководство по задаче. «Как получать изменения статуса заказа» в пять шагов: зарегистрируйте URL, обработайте подпись, ответьте 200 в течение 5 секунд, реализуйте логику повторных попыток на своей стороне, дедуплицируйте по ID события. Руководство отвечает на вопрос, на который не может ответить справочник: что мне делать со всеми этими полями.
5. Получите ревью от того, кто не писал код. Если второй интегратор может пройти по шагам без вопросов, документ работает. Если он спрашивает «какой алгоритм подписи?» — вы нашли дыру.
Что ломается, если делать иначе? Пропустите шаг 2 — напишете «статус может измениться»: технически верно, на практике бесполезно. Пропустите шаг 4 — интеграторы будут неделями заваливать поддержку тикетами. Цена плохого документа по вебхуку измерима: каждый запутавшийся интегратор — это тикет в поддержку, а тикеты накапливаются.
Где ломается сама схема
Даже дисциплинированный писатель сталкивается с провалами, не связанными с личным мастерством. Они структурные.
- Продукт движется быстрее документации. Релиз меняет схему ответа; обновление документа попадает в следующий спринт. Теперь справочник уверенно врёт — хуже, чем отсутствует, потому что читатель ему доверяет. Ранний сигнал: инженеры начинают отвечать на вопросы «не смотри в документацию, смотри в код». Решение: привяжите обновления документации к чек-листу релиза, а не к отдельному бэклогу. Если уже поздно, добавьте заметную дату «последней проверки» и журнал изменений, чтобы читатели видели расхождения.
- Стандарт принимают после того, как документ написан. Ваше руководство по стилю говорит одно, команда принимает общую терминологию или новый формат описания API, и половина документации теперь противоречит ему. Ранний сигнал: два названия одного объекта на разных страницах. Решение: глоссарий, за который отвечает один человек, и линтер, который отмечает запрещённые термины.
- Справочник переживает функцию. Эндпоинт устарел, но страница остаётся живой годами. Читатели интегрируются по мёртвому контракту. Ранний сигнал: никто в команде не может сказать, когда страницу последний раз открывали. Решение: баннеры об устаревании и плановый аудит — документ это продукт со своим жизненным циклом.
- Инженер уходит. Недокументированное поведение жило только в его голове. Это тихий провал: документ выглядел нормально, пока не исчез единственный, кто мог его проверить. Решение: ревью, на которых писатель должен пересказать поведение своими словами, чтобы знание было вынуждено перейти в текст.
Заметьте закономерность: это не «писатель был ленив». Это система документации не успевает синхронизироваться с меняющимся продуктом. Хорошие писатели проектируют с учётом такого дрейфа, а не делают вид, что его не будет.
Самообучение, курсы и чего это на самом деле стоит
Этому можно научиться самостоятельно. Читайте документацию известных API, возьмите продукт, которым пользуетесь, перепишите одну страницу, сравните. Это бесплатно и работает — для тех, у кого уже есть обратная связь.
Загвоздка в обратной связи. Изнутри не понять, ваш справочник ясен или ясен только вам. Дорогие ошибки — пример, набранный вручную и не соответствующий схеме, руководство, которое предполагает контекст, которого у читателя нет, — именно те, которых вы в одиночку не увидите. Вот честный компромисс: самообучение стоит времени и не даёт никого, кто проверил бы ваши решения.
Курсы сжимают цикл. Структурированная программа даёт этап ревью и словарь стандартов — разницу между «читается нормально» и «следует известному соглашению о кодах ошибок и версионировании». Цена — деньги и фиксированный темп. Если вам нужна отправная точка, закрывающая разрыв в обратной связи, программа «Технический писатель» строит каждый модуль вокруг законченного документа, так что вы практикуете настоящую единицу работы, а не читаете о ней. Уроки текстовые и адаптируются под ваш уровень. Начать можно здесь: Технический писатель.
Есть и третий путь, который стоит назвать: возьмите задачу по документации на работе, хотя бы одну страницу, пусть даже неоплачиваемую, и найдите старшего писателя для ревью. Медленно, но обратная связь настоящая.
Кому это подходит — и кому нет
Подходит людям, которые любят задавать точные вопросы и ненавидят неоднозначность: инженерам, движущимся к письму, сотрудникам поддержки, которые уже переводят путаницу клиентов в ясные ответы, меняющим профессию, кто умеет читать схему и стек вызовов. Это вознаграждает терпение к деталям и низкую терпимость к «и так сойдёт».
Не подходит тем, кто хочет писать маркетинговые тексты или ожидает, что работа будет в основном прозой. Большая её часть — структура, проверка и расспрашивание инженеров одним и тем же вопросом тремя способами, пока ответ не станет однозначным. Если это кажется нудным, так и будет.
Курс проходит через именно эту работу — написание справочников, ревью, стиль и терминологию — и даёт обратную связь по вашим документам. Подробности и запись на странице «Технический писатель». Начните с одной страницы, которой пользуетесь и не понимаете; переписать её — самый быстрый способ узнать, ваша ли это работа.