Про важность документирования

Многие из нас работают в компаниях с уже устоявшимися процессами разработки прикладного ПО, и неотъемлемой частью этих процессов являются самые разнообразные документы. Однако, есть компании, в которых нет традиций и процессов написания технической документации, а вся информация находится у людей в головах и в корпоративной электронной почте. Если вы приходите из компании первого типа в компанию второго типа, вы очень быстро обнаруживаете, что рабочая документация нужна как воздух. Почему? Давайте рассмотрим основные типы рабочей документации в разработке ПО, и попытаемся представить себе жизнь без них.

1. Техническое задание. ТЗ — это связь бизнеса и разработки. Это тот документ, в котором бизнес и программисты приходят к единому мнению о том, что и как должно быть реализовано. Если в компании не принято писать ТЗ, то никто и никогда не сможет понять, что уже реализовано, а что — еще нет. Это неизбежно приведет к многократному дублированию функционала, так как по мере течения времени меняются люди, меняется административное деление, функции переходят из одного подразделения в другое и так далее. Кроме того, станет чертовски сложно дополнять уже реализованный функционал новыми возможностями, потому что для того, чтобы понять (особенно новому сотруднику), что и как было реализовано, придется разговаривать с десятками сотрудников и поднимать месяцы корпоративной переписки.

2. HLA (high level architecture). Это документ описывает на уровне архитектуры, как мы будем реализовывать то, что описано в ТЗ. Расписывается, в какие места будет необходимо внести изменения, описывается суть изменений, и именно в этом документе описывается такая очень важная часть, как интерфейсы между модулями/подсистемами. Если не ошибаюсь, у ДеМарко и Листера было очень верно было отмечено, что самые «плохие» (то есть сложные в поиске и ликвидации) баги возникают при взаимодействии между системами, в интерфейсах. Так как HLA согласуется группами разработки, то, фактически, этот документ является тем единым местом, в котором группы разработки соглашаются, как их продукты будут взаимодействовать между собой. Если вы не будете писать эти документы, то вы никогда не найдете, кто неверно реализовал интерфейс, что в итоге непременно приведет к ошибкам в архитектуре, которые в будущем могут обойтись весьма большими издержками. Сильно упадет качество кода, возникнет масса труднолокализуемых ошибок. Кроме того, в будущем, для того, чтобы понять, как устроено взаимодействие между двумя модулями, новому человеку опять же придется общаться с десятками людей и поднимать месяцы переписки.

3. LLD (low level decomposition). Это документ, который создается внутри группы разработки. Он подробно описывает все необходимые к реализации методы и API. Фактически, после написания этого документа остается лишь закодировать описанное. Без этого документа программисты не будут иметь четкого понимания, что необходимо сделать, что в дальнейшем приведет к росту количества багов (то есть к снижению качества кода).

4. ПМИ (программа и методика испытаний). Это, пожалуй, основной документ из области тестирования, пошагово описывающий, что необходимо сделать для того, чтобы бизнес однозначно решил, что реализованный функционал работает корректно и согласно ТЗ. Без такого документа вы не сможете проверить функционал на предмет ошибок (несоответствие ТЗ — тоже баг), что в итоге сильно повысит риск того, что на производственной платформе вылезет куча багов, вплоть до полной неработоспособности функционала. Кроме того, без этого документа приёмка функционала бизнесом превращается в неформализованный процесс со всеми вытекающими из этого последствиями типа необоснованных претензий к разработке со стороны бизнеса.

5. Руководство пользователя. Что нужно сделать пользователю, чтобы выполнить некий бизнес-процесс с помощью вашего ПО. Много скриншотов, мало слов. Без этого документа пользователи будут регулярно по каждому чиху звонить в поддержку и (в особо запущенных случаях) в разработку. Надо ли говорить, что новому сотруднику без этого документа будет крайне сложно разобраться в прикладном ПО предприятия, которое, как правило, не отличается легкостью и интуитивной понятностью интерфейса?

6. Руководство системного администратора. Крайне необходимый документ, описывающий, какие ресурсы нужны прикладному ПО, как это ПО настраивать и как в нем раздавать привилегии и права. Документом пользуются как сисадмины, так и техподдержка (это не везде одно и то же подразделение). Без этого документа ваше ПО рискует в самый ответственный момент остаться без ресурсов (ядра CPU, место на диске). Также возникнет куча проблем со своевременностью раздачи прав: если информация в голове у двух человек, один болеет, другой в отпуске, то, чтобы сотруднику получить нужные привилегии, придётся недельку подождать. Неделька — это очень большой срок для бизнеса. Для бизнеса даже час слишком долго.

Понятно, что в этой статье рассмотрены далеко не все документы, сопровождающие процесс разработки от появления необходимости в чем-то до реализации этого чего-то на производстве. Я вообще не затронул область управления проектами, а в этой области документация — это основа основ. Я не описал все документы разработки и тестирования. Но, надеюсь, я убедил вас (неужели есть люди, которых надо в этом убеждать?) в том, что техническая документация — это крайне нужная и полезная вещь, которой ни в коем случае не стоит пренебрегать при разработке ПО.

Пишите документы!