Всем привет! Я системный аналитик в компании «СИБИНТЕК-СОФТ». Последние несколько лет занимаюсь разработкой ИТ-продуктов и сталкиваюсь с одной и той же проблемой – документация есть, но ее не читают. В чём причина — в лени разработчиков или в плохо написанной документации? Давайте разберёмся.
Важно: речь в статье идёт именно о внутренней технической документации для команды разработки: архитектурных решениях, описании сервисов, API и т.д. Это не про инструкции пользователей или администраторов и не про проектную документацию для заказчика.
Проблематика
Если в вашем чате постоянно задают одни и те же вопросы, а ответы на них уже есть в Confluence — вы точно сталкивались с тем, что разработчики не читают документацию.
Я пришла на проект, став первым системным аналитиком в команде, и начала формировать техническую документацию для разработчиков. Поначалу я сталкивалась с тем, что разработанный функционал не совпадал с ожиданиями заказчиков, и регулярно слышала вопросы следующего плана:
«Где это описано?» — «А, я не видел».
Конечно, первая моя реакция была: «Как же так? Почему никто не читает документацию? Я же столько времени на неё потратила!». Но негодование не решает проблемы. Я решила разобраться в причинах и только потом — искать решения.
Причины проблемы
Эпоха быстрого потребления
Мы все живём в мире, где информация должна быть мгновенной: соцсети, короткие видео, чаты, ИИ-ассистенты. Мы привыкли получать ответы здесь и сейчас, без погружения и усилий.
Конечно, для восприятия намного проще посмотреть видео, а не прочитать текст. Различные туториалы и «быстрые гайды» создают иллюзию понимания, но не дают глубины. Кроме того, в эпоху нейросетей и ИИ люди все чаще ждут мгновенного ответа на вопросы. Задал вопрос, получил ответ и код готов. Это отличный инструмент для ускорения работы, но помощь ИИ часто воспринимается как готовое решение без необходимости проверки.
Все это усложняет процесс чтения документации, ведь для этого требуется концентрация, усидчивость и погружение в контекст.
Плохая документация
Не будем скрывать: документация часто плохо написана. Она может быть не актуальной, написана разным стилем, с большим количеством «воды» и еще — на 100+ страниц. Естественно, легче спросить у аналитика, чем пытаться разобраться в таком тексте.
Что с этим делать
Перестаньте пересказывать документацию
Если вам задают вопрос, ответ на который уже есть в документации, не объясняйте заново, а ссылайтесь на конкретный раздел. Это экономит время и формирует привычку читать.
Актуализируйте описание своевременно
Если документация не будет отражать актуальную информацию, то она не станет единым источником истины. Старайтесь после каждого принятого решения на встрече фиксировать изменения в документации и направлять ссылку с ней всем участникам.
Сообщайте об изменениях в документации
Обязательно уведомляйте команду об изменениях - недосказанность может стоить большого количества потерянного времени на переработку. Никто не мониторит изменения документации каждый день. Кратко опишите в общем чате, что именно поменялось, и дайте ссылку на обновлённый раздел. А еще лучше будет повторить это на общей встрече, например, дейли.
Соблюдайте единый стиль написания
Когда стиль единый, проще ориентироваться и искать нужную информацию. Сформируйте для себя шаблоны, общую структуру описания и следуйте ей в каждом новом файле. Оставляйте внутри перекрестными ссылки и якори на другие разделы, чтобы было проще искать более подробную информацию.
Используйте картинки и схемы
Документация — это не только текст. Картинки упрощают понимание и визуализируют связи. Но каждая схема или диаграмма должна быть описана словами. К счастью, у системных аналитиков есть большой инструментарий для создания визуализации: диаграммы последовательности, модели данных, C4-диаграммы, BPMN и многие другие схемы.
Используйте инструменты с версионированием
Word — не лучший формат для живой д��кументации. Лучше использовать инструменты, которые поддерживают версионирование и интеграцию с процессом разработки: wiki-системы или Markdown в репозитории. Так намного проще отследить изменения и откатить все обратно.
Придерживайтесь иерархии
Человек намного лучше воспринимает иерархически организованную информацию, чем сплошной текст. Используйте разделы, подразделы и оглавление для удобства поиска и восприятия. Однако важно не переусердствовать с дроблением, слишком глубокая вложенность может запутать. Если информации слишком много, то лучше разделить ее на разные области контекста и уже внутри них выстроить иерархию.
Заключение
Разработчики не перестали читать документацию только потому, что стали ленивыми или менее профессиональными. Они адаптировались к среде, где информация потребляется очень быстро. Поэтому и документации необходимо адаптироваться под новые реалии. Если она будет краткая, но полная, со схемами и пояснениями, в едином стиле и актуальная - то она начнет работать.
Если количество вопросов по работе системы заметно сократилось — значит вы на верном пути. Успехов и терпения во внедрении документации в процессы разработки!
