Процесс документирования и документирование процесса.

Надо ли писать документы в процессе разработки, зачем и как много? Это тема одного из вечных программерских холиваров.

В 1992 году я с приятелем начал разрабатывать программу для одной конторы,
занимавшейся обменом квартир. Если кто помнит, тогда почти все квартиры были государственными (кроме кооперативов и частных домов) и их не продавали и покупали, а меняли. Причем схемы обмена бывали порой весьма замысловатыми. Тогда это был бизнес. А для нас это был первый «коммерческий проект». Естественно ни о какой документации речи тогда не шло. О документации мы вообще ничего не знали. Нет, конечно, мы были в курсе, что все инженерные системы, да и программные тоже, имеют пухлые альбомы фиолетовой документации отвратительного качества, размноженные на светокопии. Мы даже читали замечательную документацию пакета Borland Turbo Vision (кстати, это был действительно выдающийся документ, который привил мне правила хорошего тона кодирования на всю оставшуюся жизнь). Но то была пользовательская документация. О документации процесса разработки мы тогда просто не думали (впрочем, как и о многих других вещах). У меня на руках была собственноручно написанная оконная GUI библиотека для CRT режима, которую просто необходимо было опробовать на каком ни будь приложении, а у моего приятеля был заказчик, которому была нужна программа для его бизнеса по обмену квартир.

Сбор требований свелся к получасовой беседе, из которой мы узнали: примерный размер клиентской базы, какие параметры квартир надо хранить, и самое главное - если наша программа сможет подбирать из базы варианты двойных обменов квартир – наш заказчик будет просто счастлив.

Программу мы сделали. По нашим представлениям это была замечательная программа, она подбирала варианты двойных обменов. Но заказчику она не очень понравилась. Он путался в окнах, кнопках и выпадающих меню.

Я думаю, это достаточно типичная картина для времен становления индустрии коммерческой разработки ПО. Нет, я конечно, понимаю, что уже в те времена существовали и IBM, и министерство обороны США, где эти процессы были на очень высоком уровне. И книге Брукса «Мифический человеко-месяц» в тот год исполнилось 17 лет. Но то было время, когда в бурно развивающуюся у нас отрасль коммерческой разработки ПО, люди приходили весьма замысловатыми путями, и каждый учился на собственных ошибках. В последующие годы, работая во многих местах, мне часто приходилось писать код по требованиями, пересказанным устно через третьи руки. Потом этот код многократно переписывался и правился, пока не достигал нужной кондиции. Это конечно напрягало. Для многих программистов несбыточной мечтой было писать код по Техническому заданию (ТЗ).

Время шло, индустрия развивалась. Все большее число людей начинало понимать, что ТЗ это очень удобная штука не только для написания кода, но и при сдаче программы заказчику. Повсеместно появлялись различные ТЗ, ТП, ПТ и прочая документация. Устраиваясь на работу, программист спрашивал: «Вы пишете по ТЗ?», и ему все чаще отвечали «Да». Часто толку от этого бывало чуть, а сами ТЗ составлялись по следам уже написанного кода (для этого даже термин есть - reverse engineering).
Но тут неожиданно выяснилось, что вполне можно успешно разрабатывать софт и без обильной документации. На сцену вышел Кент Бек и компания со своим Экстремальным программированием (XP). Все это выглядело как грандиозное надувательство. Однако на деле оказалось, что действительно, используя совокупность продвинутых инженерных и социальных практик можно создавать программы, за которые заказчик не набьет тебе лицо, и при этом не особо заморачиваться документированием процесса.

С тех пор и повелось, что при обилии документации мы ворчим, что нам не когда писать код, а при ее отсутствии, что наш код работает не так потому, что нигде не написано, как он должен работать. Что лучше, расписывать все до последней кнопки на экране и до последнего условия в алгоритме проверки счета, и бесконечно согласовывать эти документы, или всякий раз идти и спрашивать об этом заказчика? На этот вопрос ответа нет.

Сейчас я работаю в организации, которая сертифицирована на CMMI 5 уровня. У нас определено 148 типов(!) различных документов, которые используются в процессе разработки. Помимо этого, существует так называемый “process tailoring” - индивидуальная подгонка процесса разработки под конкретный проект, когда мы можем сказать, какие конкретно документы будут использованы в проекте, а какие нет. И тем не менее, компания активно использует различные варианты Agile методологий во многих проектах. Так что же лучше - сквозное и подробное документирование, или гибкость и разработка непосредственно по запросам заказчика?

Как всегда, «истина где-то рядом». К сожалению, хорошо документированные проекты проваливаются ничуть не хуже, чем вовсе не документированные, но очень гибкие. Если бы сквозное и подробное документирование всего и вся от требований до планов и результатов тестирования было серебряной пулей, которая спасает проекты от краха, то тогда, наверное, не расцветали бы махровым цветом различные Agile методики разработки. Подробное документирование многократно увеличивает затраты и время разработки, и совершенно трагическим образом удорожает ее. Специалисты, которые создают основные документальные артефакты – аналитики, архитекторы, менеджеры проектов, стоят не в пример дороже программистов, а вот качество их работы оценить бывает очень трудно. Разрушительный эффект, который способен произвести на проект плохой архитектор или аналитик бывает просто поразительным.

У Agile свои проблемы. Когда через квартал после сдачи проекта, разъяренный пользователь пытается выяснить «почему этот отчет не учитывает те суммы» - никто не может ему ответить. Степень удовлетворенности заказчика зачастую страдает из–за того, что невозможно отследить изменения требований, а порой и сам факт того, что требования реализованы должным образом. И копание в бэклогах проекта (если они есть) обычно мало помогает.

Документация конечно нужна. Вопрос – в каком количестве и какого качества. Факторов, влияющих на то, сколько и каких документов вам потребуется, огромное количество, это:
• Специфика предметной области проекта
• Специфика продукта: внутренний, внешний, или коробочный продукт
• Специфика заказчика и даже отношений с ним
• Специфика инструментов разработки и архитектуры системы
• Квалификация разработчиков и других членов проектной команды
• Сроки и продолжительность проекта
• Кто и как будет осуществлять развертывание и поддержку продукта.

Однозначно не стоит писать документы, которые не будет читать никто кроме автора (если конечно от этого не зависит ваша проектная премия :). Не стоит писать документы, которые дублируют исходный код программы, если только вы не передаете впоследствии программу на поддержку другой команде. Многостраничные use case часто могут заменить простые прототипы, а архитектурные описания – диаграммы компонент и классов. Но тут надо быть осторожным. Все зависит от специфики предметной области и квалификации разработчиков.

В общем, вам решать – каким будет процесс документирования и документирование процесса.