Вопрос 13) Документирование программ
Один из стереотипов, бытующих в среде российских и зарубежных разработчиков программного обеспечения, — отношение к проектной документации как к второстепенному атрибуту, замедляющему работу.
Документирование ПО – процесс подготовки документации. Целью документирования является обеспечение заинтересованных читателей о функциях и структуре системы на том уровне, который обеспечивает их понимание на том уровне, который необходим применительно к решаемым им задачам.
Требования к документации
Для успешной реализации документированием поставленных перед ним задач необходимо, чтобы получаемая на выходе документация отвечала ряду требований.
1. Актуальность. Соответствие документации на ПО тому ПО, которое она описывает и отсутствие разночтений между реальными и задокументированными его параметрами и функциями.
2. Полнота. Отсутствие параметров и функций системы, которые не задокументированы.
3. Универсальность. Возможность использования на различных этапах разработки и эксплуатации ПО.
4. Стандартизованность. Использование во всей документации на ПО общих стандартов оформления и терминологии.
Классификация и виды документации
Документацию, используемую в проектах разработки программного обеспечения, можно разделить на следующие группы: Документация проекта и Документация продукта.
|
|
2) Необходимыми атрибутами планов являются: собственно описание требуемых действий; информация о событиях, «запускающих» эти действия; описание взаимной зависимости действий между собой; информация об исполнителях. Календарный план, кроме этого, содержит информацию о прогнозируемых датах начала и окончания действий.
3) Задания, выдаваемые исполнителям, подлежат документированию в целях исключения их «забывания» и двоякого толкования.
4) Отчеты о ходе работ применяются для информирования руководства и заказчика о статусе проекта.
5) Всякий сколько-нибудь сложный проект немыслим без формальных и неформальных, запланированных и спонтанных обсуждений, посвященных самым разным вопросам. Эти обсуждения могут происходить в форме очных встреч, по телефону и по переписке. Итоги устных обсуждений целесообразно фиксировать в форме протокола.
6) Ход мероприятий, которые завершаются принятием ключевых для проекта решений, отражается в отчетах, представляемых на рассмотрение лицу, принимающему решение.
7) Журнал— накопительное перечисление тех или иных однотипных событий или фактов, возникающих в ходе проекта.
1) Технические требования, или требования к системе, описывают функциональность, которую должен содержать продукт, а также ожидания заказчика относительно производительности, отказоустойчивости, надежности системы, среды, в которой она должна работать и т.д.
Исполнитель заинтересован в детализации и фиксации требований как можно раньше, чтобы избежать перепланирования, связанного с изменением требований, и чтобы цель в виде окончания проекта была ясно видна. На практике этого не происходит — каждый проект в ходе разработки в той или иной степени подвержен изменению требований
2) Технические спецификации содержат описание архитектуры программного продукта и примененных в нем технических решений. Детальность и содержание этих спецификаций в основном зависит от сложности предметной области, нестандартности примененных решений, квалификации разработчиков и распределения задач между ними.
Минимальный набор технических спецификаций содержит общее описание архитектуры и интерфейсов между компонентами, создаваемыми разными разработчиками.
3) Сведения о выпуске описывают фактически реализованную функциональность и ошибки, исправленные в данном выпуске системы, а также различные особенности выпуска: среду, в которой продукт тестировался, отклонения от требований, неисправленные ошибки и т.д. В некотором смысле они представляют собой отчетный документ, так как от каждого выпуска заказчик ожидает определенных свойств и качества.
4) Необходимость и формат представления руководства пользователя всегда диктуются заказчиком, и, следовательно, работы по его составлению так или иначе бюджетируются и оплачиваются. Аналогичные ожидания в отношении инструкций администратора могут не быть сформулированы в случае, если административную поддержку системы предполагается поручить разработчикам. При оценке необходимой детальности инструкций в этом случае следует принимать во внимание, что поддержка, как правило, осуществляется младшим персоналом, который часто сменяется и не имеет постоянного контакта с разработчиками. Отсутствие инструкций затрудняет передачу знаний, привнося искажения, а наличие в системе недокументированных особенностей рано или поздно приводит к утрате знаний, передаваемых «из уст в уста», ухудшая способность исполнителя выполнять свои обязательства.
Стандарты документирования программных средств
Существует множество стандартов, методологий и инструментальных средств для создания и разработки документации на программные системы. Основу отечественной нормативной базы в данной области составляет комплекс стандартов ЕСПД, основная часть которой была разработана в 1970-80е годы. Данный комплекс в основном охватывают ту часть документации, которая создается в процессе разработки ПС и связаны по большей части с документированием функциональных характеристик ПС.
Наиболее часто используются следующие:
ГОСТ 19.201-78 ЕСПД Техническое задание
ГОСТ 19.202-78 ЕСПД Составление спецификации
ГОСТ 19.301-79 ЕСПД Программа и методика испытаний
ГОСТ 19.401-78 ЕСПД Текст программы
ГОСТ 19.402-78 ЕСПД Описание программы
ГОСТ 19.404-79 ЕСПД Пояснительная записка
ГОСТ 19.503-79 ЕСПД Руководство системного программиста
ГОСТ 19.401-79 ЕСПД Руководство программиста
ГОСТ 19.402-79 ЕСПД Руководство оператора
ГОСТ 19.404-79 ЕСПД Руководство по техническому обслуживанию
ГОСТ Р ИСО/МЭК 9294-93 полностью соответствует ИСО/МЭК ТО 9294:1990
Информационная технология. Руководство по управлению документированием ПО.
ГОСТ Р ИСО/МЭК 9127-94 полностью соответствует ИСО/МЭК ТО 9127:1989
Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов.
Общие требования к пользовательской документации на программные средства наиболее полно представлены в стандарте IEEE 1063-1987 (подтвержден в 1993 году) «Пользовательская документация на программные средства».
Документация, методологии и стандарты качества
Никакой стандарт и никакая модель качества не требуют, чтобы проектные документы имели ту или иную структуру, форму, название или контент. Они могут лишь предполагать наиболее очевидные решения, которые, однако, никоим образом не являются обязательными. Требования стандартов и моделей заключаются в том, что информация определенного рода должна быть зафиксирована в том или ином виде, при этом не обязательно в отдельном документе. В зависимости от размера и специфики проектов в общем случае допускается создавать единые документы для группы проектов.
Форма и структура представления проектной документации, наиболее полно отражающие специфику проектов, которые в то же время достаточно удобны в использовании и не занимают при работе с ней много времени, являются уникальными для каждой организации.