Документація не потрібна рівно до того дня, коли людина, яка тримала систему в голові, іде у відпустку, в іншу компанію або просто забуває, чому п'ять років тому зробили саме так. Від цього дня кожне доопрацювання починається з розкопок, новий підрядник просить аудит перед оцінкою, а співробітники вчаться працювати в системі з переказів колег.
Документування перетворює знання окремих людей на актив компанії. Це напрям із блоку корпоративного розвитку: його підключають, коли продукт уже працює і переходить від MVP до MMP та MLP. Орієнтир вартості напряму в прайсі Ingello: $4700.
У що обходиться система без опису
- Кожна оцінка доопрацювання починається з вивчення коду, і Ви платите за те, щоб підрядник зрозумів уже зроблене.
- Ключовий розробник стає незамінним, і його відхід зупиняє розвиток продукту.
- Нова людина в команді входить у проєкт тижнями, ставлячи запитання тим, хто зайнятий своєю роботою.
- Зовнішній партнер не може підключитися до Вашого API без дзвінків і усних пояснень.
- Підтримка відповідає на ті самі запитання користувачів, бо відповідь ніде прочитати.
Є й прямий грошовий ефект. За нашими правилами аудит наявної системи можна пропустити, лише якщо є актуальна документація бізнес-процесів, архітектури, кодової бази та нормалізована схема даних. Без них будь-яка нова команда спершу відновлює картину, і цю роботу оплачуєте Ви.
Що входить у роботу
У прайсі напрям описано трьома пунктами: технічна документація, користувацька документація та база для довгострокової підтримки й розвитку проєкту.
Технічна документація
- Архітектура: з яких частин складається система, як вони пов'язані та де розгорнуті.
- Модель даних: таблиці, зв'язки та зміст полів простою мовою.
- Опис API для фронтенду, мобільного застосунку та партнерів.
- Бізнес-правила: статуси, ролі, розрахунки та те, що відбувається за кожної події.
- Порядок розгортання та відновлення після збою.
Користувацька документація
- Інструкції за ролями: менеджер, оператор, бухгалтер, адміністратор.
- Покрокові описи типових операцій із поясненнями до екранів.
- Відповіді на запитання, які найчастіше надходять у підтримку.
База для підтримки та розвитку
- Єдине місце зберігання, зрозуміле і розробникам, і бізнесу.
- Правило оновлення: зміна в системі не вважається завершеною, доки не оновлено її опис.
Найцінніше документувати рішення, а не функції
Перелік екранів застаріває за місяць. Не застаріває запис про те, чому обрали такий спосіб і що розглядали як альтернативу. Він пояснює систему новій людині швидше, ніж читання коду, і захищає від повторення помилок, які команда вже колись розібрала.
Користувацька частина заощаджує на підтримці
Особливо в системах, де лінійний персонал часто змінюється. Інструкція, прив'язана до ролі (хто ти в системі, з чого почати, що робити крок за кроком), дешевша, ніж щоразу навчати наживо кожного нового співробітника.
Що Ви отримуєте
- Незалежність від конкретного розробника та конкретного підрядника.
- Основу для технічного завдання на доопрацювання без повторного аудиту.
- Швидкий вхід нових людей у команду розробки та в роботу із системою.
- Опис API, за яким партнери підключаються самостійно.
Скільки коштує і від чого залежить
Орієнтир у прайсі: $4700 за напрям. Обсяг залежить від кількості модулів, ролей та інтеграцій, а також від того, з чого починаємо. Якщо систему проєктували в нас, основою слугує технічне завдання та моделі, створені на старті. Якщо проєкт дістався від іншої команди, спершу потрібен аудит ($800 за текстовий звіт або $2400 з раннім прототипом доопрацювання): у ньому відновлюються архітектура, ключові бізнес-процеси та модель даних, і ці матеріали стають каркасом документації.
Що ламається, якщо заощадити
- Відхід однієї людини перетворюється на зупинку проєкту.
- Кожне наступне доопрацювання дорожче, бо починається з вивчення вже зробленого.
- Зміна підрядника потребує аудиту, який довелося б оплачувати знову і знову.
- Документація, написана один раз «для галочки», за пів року розходиться із системою і починає вводити в оману.
Приклад із практики
У нашій технології Fractal частину документації не пишуть вручну, а будують із того самого опису, що й код. Для кожної моделі генерується REST API з документацією Swagger, за якою фронтенд або мобільний застосунок підключаються без усних пояснень. Директиви бізнес-логіки, записані в описі екрана, реєструються в документації та перетворюються на заготовки методів. Тому опис не розходиться із системою: він і є її джерелом.
Для корпоративного софту німецького холдингу цю мову опису використали для сутностей, бази даних, API та частини документації. Детальніше в кейсі про ШІ-програміста, який пише за архітектурою.
Куди далі
Суміжні напрями: рефакторинг та автоматизація тестування. Приймання проєкту описано в етапі тестування та передачі. Мапа всіх етапів у стратегії розробки застосунку.
На безкоштовній консультації архітектор Ingello розбере, що про Вашу систему вже записано, а що живе лише в головах, і запропонує порядок документування. Після неї Ви отримуєте розрахунок ціни й термінів за етапами. Обговорити супровід.
