Технический писатель, документация.
16 постов 0 подписчиков 0 подписок 0 лайков
Документация на проекте есть, но люди всё равно пишут в саппорт «как сделать X?». Открываешь страницу — там дана функция doX(opts) с типизацией параметров и описанием каждого поля. Формально полная…
Татьяна Котова Внутренний сервис, к которому ходят два-три соседних сервиса в той же команде. Документации нет — «и так все знают, что туда писать». Через год команда вырастает, ходоков становится десять, половина…
Татьяна Котова «Сервис недоступен», «база переключилась на реплику», «алерт HighDiskUsage сработал». Что делать в три ночи on-call инженеру? Если ответа нет — он будит других, разбирается на лету, и инцидент длится…
Татьяна Котова OpenAPI 3.1 вышел в 2021, и до сих пор половина команд сидит на 3.0, потому что «там же всё работает». Работает, да. Только когда надо описать поле, которое одновременно строка и null, или сослаться…
Татьяна Котова Документация написана, но в ней десять разных стилей. Один автор пишет «нажмите кнопку», другой — «нужно нажать на кнопочку». В одной странице — Imperative («Run the command»), в другой — descriptive…
Татьяна Котова Сервис вышел из строя в три ночи. Хорошие команды разбираются, что случилось, и через пару дней пишут постмортем — документ, который объясняет инцидент и закрывает выводы. Плохие команды ищут…
Татьяна Котова Документация про API часто пишется с прицелом «для разработчика». Что это значит на практике — никто не уточняет. И один и тот же текст оказывается одновременно слишком подробным для опытных и…
Татьяна Котова Команда выросла, репозиториев стало больше, и в какой-то момент возникает вопрос: на чём писать документацию. Раньше брали Sphinx или GitBook, в 2026 выбор обычно сводится к трём: Docusaurus, MkDocs…
Татьяна Котова Есть документация на русском. Хочется ещё на английском, чтобы продукт был доступнее. Команда переводит первую партию страниц, потом две минорные версии не успевает, потом начинают расходиться…
Татьяна Котова Релиз 2.4.0. В changelog написано: «bug fixes and improvements». Пользователь обновляется, у него ломается интеграция, он идёт смотреть, что поменялось — и видит ту же строку. В тикете «что вы…
Татьяна Котова Документация API без работающих примеров — половина документации. Человек открывает страницу, видит curl-команду, копирует в терминал, получает ошибку. Поправил кавычки — снова ошибка. Поменял URL —…
Татьяна Котова Проект разрастается. Документация — частично в README, частично на Wiki, частично в коде, и ещё какие-то страницы команда написала когда-то на Notion. Когда разработчик ищет ответ на конкретный…
Татьяна Котова Каждое неочевидное архитектурное решение через год задают повторно. «А почему мы используем Postgres, а не MongoDB?». «Почему очередь на Redis, а не на Kafka?». «Почему всё в одном репозитории, а не…
Татьяна Котова Открываешь репозиторий чужой библиотеки. Хочешь понять: что это, зачем, как поставить, как убедиться, что подходит. Скроллишь README — и видишь полотно из бейджей, длинное «about the project»,…
Татьяна Котова Платформенная команда строит инфраструктуру, на которой работают другие команды. CI, deploy-пайплайны, общие библиотеки, kubernetes-кластеры, observability-стек. Документация платформы — это не «про…
Татьяна Котова API возвращает 400 Bad Request с телом {"error":"invalid"}. Клиент видит это и не понимает: что именно невалидно, какое поле, что показать пользователю в форме. Через неделю таких ошибок в саппорт…
Татьяна Котова