llms.txt: зачем нужен и как его сделать на сайте
В 2024 году сообщество начало обсуждать формат llms.txt — файл, который сайт кладёт в корень, чтобы LLM-агенты могли быстро понять структуру и взять самое важное без полного парсинга. К 2026 году это…
#documentation
19 постов
ADR на проекте: как фиксировать архитектурные решения, чтобы их потом читали
За двенадцать лет я приходил в проекты, где «вся архитектура — в голове у Васи, который уволился полгода назад». Каждый раз одно и то же: команда боится трогать ключевые куски, потому что не…
109 18K
Алексей Морозов Туториалы vs reference: как разделить два жанра в документации
Документация на проекте есть, но люди всё равно пишут в саппорт «как сделать X?». Открываешь страницу — там дана функция doX(opts) с типизацией параметров и описанием каждого поля. Формально полная…
123 10K
Татьяна Котова Документация внутренних API: минимальный жизненный набор
Внутренний сервис, к которому ходят два-три соседних сервиса в той же команде. Документации нет — «и так все знают, что туда писать». Через год команда вырастает, ходоков становится десять, половина…
298 14K
Татьяна Котова Runbook vs playbook: что писать для on-call инженера
«Сервис недоступен», «база переключилась на реплику», «алерт HighDiskUsage сработал». Что делать в три ночи on-call инженеру? Если ответа нет — он будит других, разбирается на лету, и инцидент длится…
252 12K
Татьяна Котова OpenAPI 3.1 vs 3.0: что реально поменялось и стоит ли мигрировать
OpenAPI 3.1 вышел в 2021, и до сих пор половина команд сидит на 3.0, потому что «там же всё работает». Работает, да. Только когда надо описать поле, которое одновременно строка и null, или сослаться…
111 16K
Татьяна Котова Vale и Alex как линтеры документации: что в них реально полезно
Документация написана, но в ней десять разных стилей. Один автор пишет «нажмите кнопку», другой — «нужно нажать на кнопочку». В одной странице — Imperative («Run the command»), в другой — descriptive…
51 17K
Татьяна Котова Постмортем без блейма: шаблон, который работает
Сервис вышел из строя в три ночи. Хорошие команды разбираются, что случилось, и через пару дней пишут постмортем — документ, который объясняет инцидент и закрывает выводы. Плохие команды ищут…
256 19K
Татьяна Котова Как написать ТЗ на тестирование, чтобы его прочитали разработчики
ТЗ на тестирование — документ, который чаще всего пишется впустую. QA-инженер тратит два дня на формализацию, разработчики не открывают ссылку, через неделю начинаются фразы «у нас же это не было в…
104 19K
Елена Воронова 
Документация для junior и senior: как писать одну, чтобы работала для обоих
Документация про API часто пишется с прицелом «для разработчика». Что это значит на практике — никто не уточняет. И один и тот же текст оказывается одновременно слишком подробным для опытных и…
369 17K
Татьяна Котова Docusaurus vs MkDocs vs VitePress: что выбрать команде в 2026
Команда выросла, репозиториев стало больше, и в какой-то момент возникает вопрос: на чём писать документацию. Раньше брали Sphinx или GitBook, в 2026 выбор обычно сводится к трём: Docusaurus, MkDocs…
317 14K
Татьяна Котова Перевод документации ru/en без потери темпа разработки
Есть документация на русском. Хочется ещё на английском, чтобы продукт был доступнее. Команда переводит первую партию страниц, потом две минорные версии не успевает, потом начинают расходиться…
108 13K
Татьяна Котова Changelog по Keep a Changelog: как писать так, чтобы его читали
Релиз 2.4.0. В changelog написано: «bug fixes and improvements». Пользователь обновляется, у него ломается интеграция, он идёт смотреть, что поменялось — и видит ту же строку. В тикете «что вы…
231 10K
Татьяна Котова Curl-примеры в документации API: чек-лист, чтобы они работали
Документация API без работающих примеров — половина документации. Человек открывает страницу, видит curl-команду, копирует в терминал, получает ошибку. Поправил кавычки — снова ошибка. Поменял URL —…
349 19K
Татьяна Котова Diátaxis на практике: как разделить документацию на четыре жанра
Проект разрастается. Документация — частично в README, частично на Wiki, частично в коде, и ещё какие-то страницы команда написала когда-то на Notion. Когда разработчик ищет ответ на конкретный…
379 14K
Татьяна Котова ADR vs RFC vs design doc: чем отличаются и когда что писать
Каждое неочевидное архитектурное решение через год задают повторно. «А почему мы используем Postgres, а не MongoDB?». «Почему очередь на Redis, а не на Kafka?». «Почему всё в одном репозитории, а не…
312 10K
Татьяна Котова README, который читают: структура, которая работает
Открываешь репозиторий чужой библиотеки. Хочешь понять: что это, зачем, как поставить, как убедиться, что подходит. Скроллишь README — и видишь полотно из бейджей, длинное «about the project»,…
256 16K
Татьяна Котова Документация для платформенной команды: что должно быть, чего не нужно
Платформенная команда строит инфраструктуру, на которой работают другие команды. CI, deploy-пайплайны, общие библиотеки, kubernetes-кластеры, observability-стек. Документация платформы — это не «про…
104 10K
Татьяна Котова Стиль ошибок API: что вернуть в 400 и как это документировать
API возвращает 400 Bad Request с телом {"error":"invalid"}. Клиент видит это и не понимает: что именно невалидно, какое поле, что показать пользователю в форме. Через неделю таких ошибок в саппорт…
302 14K
Татьяна Котова