Всем привет! Я системный аналитик в компании «СИБИНТЕК-СОФТ». Последние несколько лет занимаюсь разработкой ИТ-продуктов и сталкиваюсь с одной и той же проблемой – документация есть, но ее не читают. В чём причина — в лени разработчиков или в плохо написанной документации? Давайте разберёмся.
Важно: речь в статье идёт именно о внутренней технической документации для команды разработки: архитектурных решениях, описании сервисов, API и т.д. Это не про инструкции пользователей или администраторов и не про проектную документацию для заказчика.
Проблематика
Если в вашем чате постоянно задают одни и те же вопросы, а ответы на них уже есть в Confluence — вы точно сталкивались с тем, что разработчики не читают документацию.
Я пришла на проект, став первым системным аналитиком в команде, и начала формировать техническую документацию для разработчиков. Поначалу я сталкивалась с тем, что разработанный функционал не совпадал с ожиданиями заказчиков, и регулярно слышала вопросы следующего плана:
«Где это описано?» — «А, я не видел».
Конечно, первая моя реакция была: «Как же так? Почему никто не читает документацию? Я же столько времени на неё потратила!». Но негодование не решает проблемы. Я решила разобраться в причинах и только потом — искать решения.
Причины проблемы
Эпоха быстрого потребления
Мы все живём в мире, где информация должна быть мгновенной: соцсети, короткие видео, чаты, ИИ-ассистенты. Мы привыкли получать ответы здесь и сейчас, без погружения и усилий.
Конечно, для восприятия намного проще посмотреть видео, а не прочитать текст. Различные туториалы и «быстрые гайды» создают иллюзию понимания, но не дают глубины. Кроме того, в эпоху нейросетей и ИИ люди все чаще ждут мгновенного ответа на вопросы. Задал вопрос, получил ответ и код готов. Это отличный инструмент для ускорения работы, но помощь ИИ часто воспринимается как готовое решение без необходимости проверки.
Все это усложняет процесс чтения документации, ведь для этого требуется концентрация, усидчивость и погружение в контекст.
Плохая документация
Не будем скрывать: документация часто плохо написана. Она может быть не актуальной, написана разным стилем, с большим количеством «воды» и еще — на 100+ страниц. Естественно, легче спросить у аналитика, чем пытаться разобраться в таком тексте.
Что с этим делать
-
Перестаньте пересказывать документацию
Если вам задают вопрос, ответ на который уже есть в документации, не объясняйте заново, а ссылайтесь на конкретный раздел. Это экономит время и формирует привычку читать.
-
Актуализируйте описание своевременно
Если документация не будет отражать актуальную информацию, то она не станет единым источником истины. Старайтесь после каждого принятого решения на встрече фиксировать изменения в документации и направлять ссылку с ней всем участникам.
-
Сообщайте об изменениях в документации
Обязательно уведомляйте команду об изменениях - недосказанность может стоить большого количества потерянного времени на переработку. Никто не мониторит изменения документации каждый день. Кратко опишите в общем чате, что именно поменялось, и дайте ссылку на обновлённый раздел. А еще лучше будет повторить это на общей встрече, например, дейли.
-
Соблюдайте единый стиль написания
Когда стиль единый, проще ориентироваться и искать нужную информацию. Сформируйте для себя шаблоны, общую структуру описания и следуйте ей в каждом новом файле. Оставляйте внутри перекрестными ссылки и якори на другие разделы, чтобы было проще искать более подробную информацию.
-
Используйте картинки и схемы
Документация — это не только текст. Картинки упрощают понимание и визуализируют связи. Но каждая схема или диаграмма должна быть описана словами. К счастью, у системных аналитиков есть большой инструментарий для создания визуализации: диаграммы последовательности, модели данных, C4-диаграммы, BPMN и многие другие схемы.
-
Используйте инструменты с версионированием
Word — не лучший формат для живой документации. Лучше использовать инструменты, которые поддерживают версионирование и интеграцию с процессом разработки: wiki-системы или Markdown в репозитории. Так намного проще отследить изменения и откатить все обратно.
-
Придерживайтесь иерархии
Человек намного лучше воспринимает иерархически организованную информацию, чем сплошной текст. Используйте разделы, подразделы и оглавление для удобства поиска и восприятия. Однако важно не переусердствовать с дроблением, слишком глубокая вложенность может запутать. Если информации слишком много, то лучше разделить ее на разные области контекста и уже внутри них выстроить иерархию.
Заключение
Разработчики не перестали читать документацию только потому, что стали ленивыми или менее профессиональными. Они адаптировались к среде, где информация потребляется очень быстро. Поэтому и документации необходимо адаптироваться под новые реалии. Если она будет краткая, но полная, со схемами и пояснениями, в едином стиле и актуальная - то она начнет работать.
Если количество вопросов по работе системы заметно сократилось — значит вы на верном пути. Успехов и терпения во внедрении документации в процессы разработки!
Комментарии (39)
JBFW
22.02.2026 13:19Однако текст читать быстрее чем смотреть видео или слушать подкасты.
Ну, если кто грамоте обучен, конечно.В остальном да, не читают, не могут.
push_ann Автор
22.02.2026 13:19Согласна, текст действительно быстрее для получения информации.
Но на практике вопрос чаще не в скорости, а в привычке потребления. Как я и писала в статье, люди всё чаще привыкают получать информацию в визуальном формате. На этом фоне воспринимать сплошной текст становится сложнее, даже если он объективно эффективнее.
Думаю, добавление визуала (схем, диаграмм) поможет быстрее понять написанный текст.
Плюс, конечно, многое упирается в качество самой документации — если она плохая, её начинают избегать независимо от формата.
akod67
22.02.2026 13:19Разработчики никогда не любили читать документацию, ещё до времён тиктоков. Потому что пишут её люди, к которым нет ни доверия ни уважения (как к технарям). Достаточно пару раз напороться на неактуальность и ошибки, и всё, доверия нет. Доверие есть только к исходному коду. А сами разработчики документацию писать не любят. LLM в этом плане просто спасение.
Замените все эти пункты на "убедиться, что документация доступна через MCP и сформирована понятным для ИИ образом". Всё остальное в топку.
push_ann Автор
22.02.2026 13:19Доверие к документации действительно легко потерять. Иногда проще пойти в код или спросить коллег. Но в этом и есть задача аналитика или технического писателя - поддерживать актуальность и точность описания.
Конечно, тот, кто пишет документацию должен быть хорошо подкован в техническом плане. Но это уже тема отдельной статьи, какими навыками должен обладать системный аналитик. Чаще всего это все-таки бывшие разработчики (я в том числе).
«Доверие есть только к исходному коду» - это справедливо в плане понимания реализации. Но код не всегда отвечает на вопрос «почему так сделано» и какие есть ограничения или договорённости.
Что касается LLM — согласна, это сильно упрощает доступ к информации. И идея делать документацию более «понятной для ИИ» звучит логично. Но, как мне кажется, это должна быть не замена, а помощь в работе.
Тем более если сама документация неактуальна или противоречива, ИИ просто будет быстрее распространять неточности и проблемы.
akod67
22.02.2026 13:19Opus прекрасно поясняет код и отвечает на большинство вопросов по нему. На много лучше, чем условный аналитик, большинство из которых код не открывают от слова вообще. Вот эта людская роль - в top 3 на вылет.
Тем более если сама документация неактуальна или противоречива, ИИ просто будет быстрее распространять неточности и проблемы.
Нет. У LLM будет доступ как к исходному коду, так и к документации (вопросы СБ давайте оставим за скобками). Причём документацию сам же LLM и будет поддерживать в актуальном состоянии. Для этого человек УЖЕ не нужен. Осталось только доступ к современным моделям распространить в массы, идеально, если в self hosted виде. Только это пока ограничивает.
push_ann Автор
22.02.2026 13:19Ключевое - поддерживать документацию, но не писать ее. В этом все равно нельзя исключать человека. Код не всегда является истиной, требования часто меняются и, соответственно, документация тоже.
akod67
22.02.2026 13:19"Код не является истиной...". С точки зрения КАК работает продукт в конкретной версии - именно код и является истиной ибо он и работает. Получается в вашей картине мира - это желаемое, а не реальное состояние продукта? Ну тогда да, толку от этой документации для программиста...
vpgromov
22.02.2026 13:19Мне тоже в статье про ведение документации начали писать, что уметь грамотно ее вести не так важно, если сейчас все делает ИИ. На самом деле, если правильно все сделать, то ИИ и не нужен будет.
В целом, я описал частично в своей статье, но чтобы вам не пришлось лезть, кратко объясню: я организую всю документацию на разных страницах-артефактах в вики, так как таким образом это не превращается в длинное полотно на 30-100 страниц, в этом легче ориентироваться и гораздо легче поддерживать. И да, каждая задача для разработчика — это отдельная страница. Ему вообще с нее не нужно уходить: там все описано, что нужно для конкретной задачи, а ссылки на другие страницы — дополнительная информация, если вдруг разработчик решит почитать, но это не обязательно для выполнения задачи.
У меня была проблема в первом ТЗ для разработчиков на этом месте работы, что ко мне приходили с вопросами "А это как делать?". Но чаще всего эти вопросы решались тем, что я указывал на какой-то абзац на той же странице задачи. Нет, задача не написана на 10 страниц, там максимум набирается страницы 2, но обычно — меньше страницы. Вся документация строго структурирована и никакой воды в ней нет: только инструкции, что сделать. Был момент, когда ко мне бэкендерша пришла с вопросом, на который был ответ буквально в следующем абзаце. Она просто не дочитала.
После работы со мной в рамках первого требования, разработчики все поняли и больше с такими вопросами не приходят)
vpgromov
22.02.2026 13:19Вообще считаю, что каждая вики должна иметь возможность вставить видео с сабвей серферс справа от статьи, чтобы удерживать внимание разработчиков)
akod67
22.02.2026 13:19Ещё раз - MCP нужен не для того, что бы ИИ пересказал документацию простыми словами и по сути (хотя и это тоже), он нужен для того, что бы ИИ сгенерировал по документации сходу правильный код.
Ожидание, что талмуд документации прочитают, запомнят, и не будут приходить с вопросами - это что-то запредельное по своей неправильности. Это можно ожидать от машины, люди - существа с быстро деградирующей памятью. Минусуйте..
vpgromov
22.02.2026 13:19У меня недостаточно кармы, чтобы минусовать, да я и не собирался)
Согласен, что подобная возможность круто смотрится. Но только с MCP, потому что если просто в отрыве от контекста отправить тзшку, то можно накодить неправильно. Хотя в большинстве своем справится
У нас на работе, к сожалению, нет встроенного в wiki ИИ. Все обещают сделать что-то свое, но пока никак. MCP для wiki подключить, конечно же, никто не даст, потому что правила безопасности не позволяют. Можно пользоваться гптшками, но не сильно погружая ее в контекст (нельзя всю базу кодовую слить)
Многое в СБ упирается
akod67
22.02.2026 13:19MCP - это примитивнейший протокол, реализовать его на коленке можно. Тут вопрос в самой реализации работы с данными - что именно он выдаёт и как. Самые простые кейсы - это технические описания API методов и т.п., банально куски текста можно пробрасывать, LLM на раз такое сжуёт и будет применять при кодогенерации. В том числе, запихивая в контекст и нюансы использования. Будет написано в документации в поле "color" зелёный пихать нельзя - она это учтёт, а вот человек наверняка пропустит, ибо никто не читает доки слово в слово.
Сложнее с автоматизацией всякой логики, но и то, если её можно описать dataflow / UML диаграммами - это всё можно в MD виде через MCP отдать и нормальная LLM с этим тоже работает.
В общем, тут меняются требования к самой документации, но ключевое - она начнёт работать, а не всё это...
vpgromov
22.02.2026 13:19Знаю, что это просто. Но не все компании готовы идти на такое. Не знаю еще по вопросу СБ: у нас в целом вики доступна только под впн.
На прошлом месте работы мы вели работу в docmost и у нас джуны писали к нему mcp, так что я понимаю, что работа не пыльная)
akod67
22.02.2026 13:19Динозавры отомрут естественным путём. Правда, процесс вымирания может затянуться =)
LittleMeN
22.02.2026 13:19Вы очень четко описали документацию, которую я читать не буду! Организация в режиме вики лично для меня категорически не удобная. Особенно если знакомишься с новым продуктом, особенно если нету последовательного повествования, с погружением в специфику продукта. Какие-то артефакты, которые разработчик продукта посчитал важными он описал, а последовательное пояснение с чего начать, как установить, как использовать и т.п. как правило хрен найдёшь в это вашей вики. Оговорюсь, в том случае если мы говорим про документацию, а не базу знаний. И даже в случае базы знаний, я не буду читать статью/артефакт, потом прыгать за другим артефактом по ссылке, потом за другим и так далее.
ReadIt-Club
Документацию нужно адаптировать под ИИ, потому что в скором времени он и только он будет ее читать
push_ann Автор
Интересная мысль, и в ней есть доля правды. ИИ уже сейчас активно используется как «прослойка» между разработчиком и документацией — чтобы быстрее найти ответ или собрать контекст.
Но я бы не стала рассматривать его как единственного читателя.
Документация всё-таки фиксирует договорённости внутри команды: архитектурные решения, ограничения, причины «почему сделано так». Это то, что важно понимать человеку, а не только получить готовый ответ.
Думаю, сейчас мы движемся к модели:
В любом случае советы, приведенные в статье, могут быть использованы для улучшения понимания текста ИИ.