Раздел 3

Документирование в процессах жизненного цикла ПО

3.1 Документация и ее роль в обеспечении качества

Документирование ПО определяется стандартами ГОСТ серии 19, 34, ГОСТ Р ИСО/МЭК 8631, ГОСТ Р ИСО 9127, ГОСТ Р ИСО/МЭК ТО 9294. Полный перечень нормативных документов на программную документацию приведен в документе Методика экспертизы программной документации, находящегося на стадии утверждения.

ГОСТ Р ИСО/МЭК ТО 9294-93 ИТ. Руководство по управлению документированием ПО является одним из основных стандартов в данной области и представляет собой руководство по документированию ПО для тех руководителей, которые отвечают за разработку программного обеспечения. Данное руководство предназначено для помощи руководителям в обеспечении эффективного проведения документирования в организациях. Данный стандарт направлен на определение стратегий, стандартов, процедур, ресурсов и планов, которыми должны заниматься сами руководители для того, чтобы эффективно управлять документированием ПО.

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

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

Эффективность выполнения руководящей роли можно рассматривать как основанную на следующих трех элементах.

1. Руководящая обязанность по документированию - требует признания того, что программная документация важна и что ее следует планировать, описывать, проверять, утверждать, выпускать, распространять и сопровождать.

2. Руководящая поддержка обязанностей персонала по документированию - требует руководство и стимулирование персонала при проведение требуемого документирования и обеспечение его ресурсами для содействия в данной работе.

3. Признаки руководящих обязанностей и поддержки - требует обеспечить:

а) опубликованные официальные отчеты о стратегии документирования;
б) стандарты и руководства, определяющие все аспекты документирования ПО;
в) опубликованные процедуры документирования;
г) выделение соответствующих ресурсов для документирования;
д) планирование документирования, осуществляемое как неотъемлемая часть процесса разработки ПО;
е) постоянную проверку, осуществляемую для обеспечения соответствия со стратегией, стандартами, процедурами и планами по документированию.

В ГОСТ Р ИСО/МЭК ТО 9294-93 программная документация рассматривается как имеющая следующие шесть основных функций.

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

2. Связь между задачами. Большинство проектов разработки ПО разделяется на задачи, выполняемые различными группами: специалисты в предметной области, аналитики, проектировщики, специалисты по обеспечению качества и др. Этим группам, а также персоналу в пределах группы, необходимы средства общения друг с другом, обеспечивающие информацию, которую можно воспроизводить, распространять и на которую можно ссылаться. Большинство методологий разработки ПО устанавливают официальные документы для связи между задачами. Например, аналитики представляют официальные спецификации требований проектировщикам, а они, в свою очередь, официальные проектные спецификации программистам.

3. Обеспечение качества. Требуется документация разработки и документация продукции для выполнения задач, связанных с обязанностями по обеспечению качества ПО.

4. Инструкции и справки. Документация, требующаяся операторам, пользователям, руководителям и другим заинтересованным лицам для того, чтобы понимать и использовать ПО.

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

6. Исторические справки. Документация, требуемая в качестве исторической справки по проекту. Данная документация может помочь в переносе и переводе ПО в новое окружение.

Рассмотрим стратегии документирования. Стратегии документирования, подготовленные и контролируемые руководителем организации, обеспечивают руководящими положениями ответственных лиц, принимающих решения на всех нижних уровнях. Стратегия обеспечивает главное направление, но не дает рекомендаций, что делать и как это делать. Из-за существенной роли, которую играет документация на всех стадиях ЖЦ ПО, стратегия должна быть официально утверждена, доведена до каждого исполнителя проекта. Официальная стратегия устанавливает дисциплину, требуемую для эффективного документирования ПО.

Стратегия должна поддерживать основные элементы эффективного документирования:

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

Внутри организации, помимо стратегии, должны быть приняты стандарты и руководства для:

модели жизненного цикла ПО;
типов и взаимосвязей документов;
содержания документа;
качества документа;
форматов документа;
обозначение документа.

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

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

какие типы документов требуются?
каков объем представляемой документации?
что документы содержат?
какой уровень качества будет достигнут?
где документы будут созданы?
как документы будут хранить, сопровождать и обращать?

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

Основными ресурсами, требуемыми для документирования, являются следующие: персонал, средства, финансирование.

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

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

Финансирование. Важно, чтобы стоимость документирования определяли как отдельные статьи бюджета, так как она нередко составляет значительную часть стоимости разработки ПО.

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

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

График документирования должен распределять время для:

планирования документов;
проверки плана и принципов документирования;
подготовки проектов и проверки их на техническую точность, полноту и соответствие;
редактирование при внесение комментариев, появившихся при проверке;
проведения согласования;
перевода;
распространения.

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

Более подробно рассмотрим стандарты и руководства, принимаемые в организации.

1. Выбор модели жизненного цикла ПО.

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

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

В рамках ИСО/МЭК 12207 документирования решаются при вызове каким-либо процессом ЖЦ процесса документирования.

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

Процесс документирования состоит из следующих действий: реализации, проектирование и разработка, производство и сопровождение.

Реализация. Это действие состоит из следующих задач.

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

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

Проектирование и разработка. Это действие состоит из следующих задач.

1. Каждый документ должен быть спроектирован в соответствии с применяемыми стандартами по формату, содержанию, нумерации страниц, размещению рисунков/таблиц, отметке о приоритете/секретности, упаковке и другим пунктам.

2. Источник и соответствие входных данных для документов должны быть гарантированы. Должны быть использованы автоматические средства документирования.

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

Производство. Это действие состоит из следующих задач.

1. Документы должны быть произведены и упакованы. В соответствии с планом, ими должны быть обеспечены все заинтересованные стороны. Производство и распространение документов может быть выполнено в бумажном, электронном виде. Исходные материалы должны храниться в соответствии с условиями записи, секретности, сопровождения и резервных копий проекта.

2. Контроль должен быть представлен в соответствии с процессом управления конфигурированием.

Сопровождение. Это действие состоит из следующих задач.

1. Задачи, необходимые для выполнения при модификации существующего ПО, должны быть исполнены.

Стадия Рабочая документация ГОСТ 34.601 частично соответствует привлечению процесса документирования процессов разработки по ИСО/МЭК 12207. Название данной стадии не точно отражает ее содержание, так как она содержит этап 6.2 - Разработка или адаптация программ. Кроме того, процесс документирования выполняется на стадиях эскизного и технического проекта. По ГОСТ 19.102 этап разработки программной документации появляется только на стадии Рабочий проект. Такое позднее начало документирования процессов ЖЦ не в состоянии обеспечить ни требуемого качества документации, ни требуемого качества ПО.

Таким образом, терминология и концепция в области документирования ИСО/МЭК 12207 представляются более удачными. Можно рекомендовать при использование ГОСТ 34.601 для этапов 4.2, 5.2, 5.3, 6.1 учитывать в содержании работ задачи, определенные в ИСО/МЭК 12207 для процесса документирования

2. Определение типов и содержания документов.

Программные документы можно представить разделенными на три категории:

документация разработки;
документация продукции;
документация управления проектом.

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

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

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

Типовыми документами разработки являются:

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

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

Документация продукции преследует три цели:

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

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

Типовые документы продукции включают в себя:

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

ГОСТ Р ИСО 9127-94 Системы обработки информации. Документация пользователя и информация на упаковке для потребительских пакетов вводит определение документации пользователя, как документации, которая обеспечивает пользователей информацией, необходимой для установки и прогона ПО и является обязательной в поставке (документация пользователя выполняется в виде одного или нескольких руководств и вкладывается вместе с программным продуктом внутрь упаковки).

Данный стандарт определяет три категории информации:

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

Назначением документации пользователя является обеспечение конечного пользователя достаточной информацией для ясного понимания:

цели, функций и характеристик ПО;
того, как ввести в действие и использовать ПО;
договорных прав и обязанностей.

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

Таким образом, ГОСТ Р ИСО 9127, не имея формальных ссылок на ГОСТ Р ИСО/МЭК ТО 9294, фактически дополняет введенное в нем понятие документации продукции.

3. Документация управления проектом. Документы создаются на основе информации управления проектом, такой как:

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

Данная документация обеспечивает информацию, относящуюся, с точки зрения руководства, к долговечности продукции.

3. Определение качества документов.

Руководители должны выбирать стандарты, распространяющиеся на уровень качества, соответственно различным типам документов и различным типам проектов и должны определять, как это качество будет достигнуто и поддержано.

Понятия качества, применимые к содержанию, структуре и представлению документации:

1. качество содержания можно измерять в элементах точности, полноты и ясности;
2. качество структуры, можно измерять легкостью, с которой читатель имеет возможность определить местоположение информации;
3. качество представления должно соответствовать типу проекта.

4. Определение форматов документов.

Стандартизованные форматы документов важны для контроля качества документов, для читаемости документов и для облегчения их сопровождения.

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

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

5. Определение системы обозначения документов.

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

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

В части требований 2 - 5 отечественные стандарты 19-ой, 34-ой серии, ГОСТ 28195-89 обеспечивают решение задачи формирования комплекта документации, что будет нами рассмотрено ниже.