Управление документацией в проектах разработки ПО

Один из стереотипов, бытующих в среде российских и зарубежных разработчиков программного обеспечения, — отношение к проектной документации как к второстепенному атрибуту, замедляющему и бюрократизирующему работу. Вместе с тем многие стандарты и модели качества, такие как ISO 9000, CMMI и COBIT, уделяют значительное внимание документации, а многие последователи различных «скорых» методик, напротив, отводят документации минимум места в своих проектах. Разумный оптимум, как обычно, находится посередине.

Документация используется для хранения и передачи знаний и фактов самого разного характера — от «глобальных» наподобие требований к системе до знаний ограниченного применения (например, список дефектов, найденных в ходе определенного раунда тестирования). Документация формализует договоренности и обязательства, под которыми можно понимать широкий спектр обещаний, намерений или заданий, циркулирующих между одной или несколькими организациями. Документы могут служить формальным контрактом, определяющим взаимные ожидания сторон. Наконец, проектная документация служит для демонстрации продвижения проекта и повышения личной ответственности его участников за результат — на многих стадиях проекта при отсутствии документально подтвержденных результатов работ убедить руководство в успешном ходе проекта становится чрезвычайно трудной задачей. Кроме этого, факт собственноручного изложения результатов работ в письменной форме является декларацией способностей и успехов исполнителя, и документацию такого рода можно использовать для восстановления истории и как основу для различного рода дисциплинарных воздействий — как положительных, так и отрицательных.

Классификация и виды документации

Документацию, используемую в проектах разработки программного обеспечения, можно разделить на следующие группы (см. рисунок): Документация проекта и Документация продукта.

Рисунок. Виды документации

Описание проекта

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

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

Планы

Необходимыми атрибутами планов являются: собственно описание требуемых действий; информация о событиях, «запускающих» эти действия; описание взаимной зависимости действий между собой; информация об исполнителях. Календарный план (schedule), кроме этого, содержит информацию о прогнозируемых датах начала и окончания действий. Наиболее распространенным видом планов является план-график проекта в нотации Ганта и Перта.

Исследовательские проекты, а также проекты, управляемые временем (time-driven project), могут обходиться без планов-графиков. В таких проектах планирование может иметь неглубокий горизонт, а планы на будущий период фиксироваться, например, в регулярных отчетах.

Теория разработки программного обеспечения (в частности, модель CMMI) также упоминает множество других планов, которыми должна сопровождаться разработка: план управления требованиями, план управления изменениями, план управления рисками, план управления конфигурациями, план тестирования и т.д. На практике в «одиночном» проекте, не носящем большой сложности, большинство из этих планов могут носить самый общий характер и ориентироваться скорее на правила взаимодействия с заказчиком, чем на описание внутренних операций.

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

Задания исполнителям и отчеты о ходе работ

Задания (task), выдаваемые исполнителям, подлежат документированию в целях исключения их «забывания» и двоякого толкования. Документальные формы, используемые для накопления и отслеживания заданий, на практике используются редко и обычно в качестве источника информации о выданных заданиях применяются: планы-графики; специально выделенные разделы в регулярных отчетах; задачи, выставленные через Microsoft Outlook или через системы управления изменениями (такие, как IBM ClearQuest).

Отчеты о ходе работ (status report) применяются для информирования руководства и заказчика о статусе проекта. Отчеты могут исходить как от конечных исполнителей, так и от менеджера проекта.

Протоколы

Всякий сколько-нибудь сложный проект немыслим без формальных и неформальных, запланированных и спонтанных обсуждений, посвященных самым разным вопросам. Эти обсуждения могут происходить в форме очных встреч, по телефону и по переписке. Итоги устных обсуждений целесообразно фиксировать в форме протокола, если приняты решения, изменяющие или дополняющие описание проекта; принято много разнообразных решений; высказаны новые идеи, например, технического характера, которые могут оказаться востребованными в дальнейшем.

Отчеты о результатах активностей

Ход мероприятий, которые завершаются принятием ключевых для проекта решений, отражается в отчетах, представляемых на рассмотрение лицу, принимающему решение. Основными мероприятиями такого рода являются: анализ осуществимости, анализ альтернатив реализации, обзор (review) проектной документации, тестирование и приемка. Протоколы этих активностей, как правило, содержат сведения о времени, объекте, рамках и характере активности, среде, в которой проводилась активность, достигнутых результатах и рекомендуемых решениях.

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

Журналы

Журнал (log) — накопительное перечисление тех или иных однотипных событий или фактов, возникающих в ходе проекта. Типичными объектами, накапливаемыми в журналах, являются риски, проблемы, запросы на изменения, дефекты (как документации, так и собственно продукта). План-график может заменяться или дополняться «журналом задач», в случае, если эти задачи носят локальный характер.

Журналы редко оформляются в виде отдельного документа. Журналы рисков и проблем обычно являются разделом в отчете о состоянии проекта; ведение журналов изменений и дефектов организуется с помощью систем управления изменениями.

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

Технические требования

Технические требования, или требования к системе (system requirements specification), описывают функциональность, которую должен содержать продукт, а также ожидания заказчика относительно производительности, отказоустойчивости, надежности системы, среды, в которой она должна работать и т.д. Часто требования являются частью контрактной документации.

Исполнитель заинтересован в детализации и фиксации требований как можно раньше, чтобы избежать перепланирования, связанного с изменением требований, и чтобы цель в виде окончания проекта была ясно видна. На практике этого не происходит — каждый проект в ходе разработки в той или иной степени подвержен изменению требований.

Технические спецификации

Технические спецификации (technical specification) содержат описание архитектуры программного продукта и примененных в нем технических решений. Детальность и содержание этих спецификаций в основном зависит от сложности предметной области, нестандартности примененных решений, квалификации разработчиков и распределения задач между ними.

Минимальный набор технических спецификаций содержит общее описание архитектуры и интерфейсов между компонентами, создаваемыми разными разработчиками.

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

Сведения о выпуске

Сведения о выпуске (release note) описывают фактически реализованную функциональность и ошибки, исправленные в данном выпуске системы, а также различные особенности выпуска: среду, в которой продукт тестировался, отклонения от требований, неисправленные ошибки и т.д. В некотором смысле они представляют собой отчетный документ, так как от каждого выпуска заказчик ожидает определенных свойств и качества.

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

Руководства

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

Документация, методологии и стандарты качества

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

Форма и структура представления проектной документации, наиболее полно отражающие специфику проектов, которые в то же время достаточно удобны в использовании и не занимают при работе с ней много времени, являются уникальными для каждой организации. Разработка оптимальной формы и структуры документации — одна из составляющих деятельности по улучшению процессов и один из предметов процессного консалтинга.

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