Документация не нужна ровно до того дня, когда человек, державший систему в голове, уходит в отпуск, в другую компанию или просто забывает, почему пять лет назад было сделано именно так. С этого дня каждая доработка начинается с раскопок, новый подрядчик просит аудит перед оценкой, а сотрудники учатся работе в системе по пересказу коллег.
Документирование превращает знание отдельных людей в актив компании. Это направление из блока корпоративного развития: оно подключается, когда продукт уже работает и переходит от MVP к MMP и MLP. Ориентир стоимости направления в прайсе Ingello: $4700.
Во что обходится система без описания
- Каждая оценка доработки начинается с изучения кода, и Вы платите за то, чтобы подрядчик понял уже сделанное.
- Ключевой разработчик становится незаменимым, и его уход останавливает развитие продукта.
- Новый человек в команде входит в проект неделями, задавая вопросы тем, кто занят своей работой.
- Внешний партнёр не может подключиться к Вашему API без созвонов и устных объяснений.
- Поддержка отвечает на одни и те же вопросы пользователей, потому что ответа негде прочитать.
Есть и прямой денежный эффект. По нашим правилам аудит существующей системы можно пропустить, только если есть актуальная документация бизнес-процессов, архитектуры, кодовой базы и нормализованная схема данных. Без них любая новая команда сначала восстанавливает картину, и эту работу оплачиваете Вы.
Что входит в работу
В прайсе направление описано тремя пунктами: техническая документация, пользовательская документация и база для долгосрочной поддержки и развития проекта.
Техническая документация
- Архитектура: из каких частей состоит система, как они связаны и где развёрнуты.
- Модель данных: таблицы, связи и смысл полей простым языком.
- Описание API для фронтенда, мобильного приложения и партнёров.
- Бизнес-правила: статусы, роли, расчёты и то, что происходит при каждом событии.
- Порядок развёртывания и восстановления после сбоя.
Пользовательская документация
- Инструкции по ролям: менеджер, оператор, бухгалтер, администратор.
- Пошаговые описания типовых операций с пояснениями к экранам.
- Ответы на вопросы, которые чаще всего приходят в поддержку.
База для поддержки и развития
- Единое место хранения, понятное и разработчикам, и бизнесу.
- Правило обновления: изменение в системе не считается законченным, пока не обновлено его описание.
Ценнее всего документировать решения, а не функции
Список экранов устаревает через месяц. Не устаревает запись о том, почему выбрали такой способ и что рассматривали как альтернативу. Она объясняет систему новому человеку быстрее, чем чтение кода, и защищает от повторения ошибок, которые команда уже однажды разобрала.
Пользовательская часть экономит на поддержке
Особенно в системах с текучкой линейного персонала. Инструкция, привязанная к роли (кто ты в системе, с чего начать, что делать по шагам), дешевле, чем повторять обучение вживую каждому новому сотруднику.
Что Вы получаете
- Независимость от конкретного разработчика и от конкретного подрядчика.
- Основу для технического задания на доработку без повторного аудита.
- Быстрый вход новых людей в команду разработки и в работу с системой.
- Описание API, по которому партнёры подключаются самостоятельно.
Сколько стоит и от чего зависит
Ориентир в прайсе: $4700 за направление. Объём зависит от числа модулей, ролей и интеграций, а также от того, с чего начинаем. Если система проектировалась у нас, основой служит техническое задание и модели, созданные на старте. Если проект достался от другой команды, сначала нужен аудит ($800 за текстовый отчёт или $2400 с ранним прототипом доработки): в нём восстанавливаются архитектура, ключевые бизнес-процессы и модель данных, и эти материалы становятся каркасом документации.
Что ломается, если сэкономить
- Уход одного человека превращается в остановку проекта.
- Каждая следующая доработка дороже, потому что начинается с изучения уже сделанного.
- Смена подрядчика требует аудита, который пришлось бы оплачивать снова и снова.
- Документация, написанная один раз «для галочки», через полгода расходится с системой и начинает вводить в заблуждение.
Пример из практики
В нашей технологии Fractal часть документации не пишется руками, а строится из того же описания, что и код. Для каждой модели генерируется REST API с документацией Swagger, по которой фронтенд или мобильное приложение подключаются без устных объяснений. Директивы бизнес-логики, записанные в описании экрана, регистрируются в документации и превращаются в заготовки методов. Поэтому описание не расходится с системой: оно и есть её источник.
Для корпоративного софта немецкого холдинга этот язык описания использовался для сущностей, базы данных, API и части документации. Подробнее в кейсе об ИИ-программисте, который пишет по архитектуре.
Куда дальше
Смежные направления: рефакторинг и автоматизация тестирования. Приёмка проекта описана в этапе тестирования и передачи. Карта всех этапов в стратегии разработки приложения.
На бесплатной консультации архитектор Ingello разберёт, что о Вашей системе уже записано, а что живёт только в головах, и предложит порядок документирования. После неё Вы получаете расчёт цены и сроков по этапам. Обсудить сопровождение.
