Государственный стандарт РФ ГОСТ Р ИСО/МЭК ТО 9294-93 "Информационная технология. Руководство по управлению документированием программного обеспечения" (утв. постановлением Госстандарта РФ от 20 декабря 1993 г. N 260)

Information technology. Guidelines for the management of software documentation

Дата введения 1 июля 1994 г.

Введен впервые

1 Область применения

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

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

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

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

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

2 Нормативные ссылки

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

ИСО 2382-84 Обработка данных. Словарь. Часть 1: Основные термины

ИСО 6592-85 Обработка информации. Руководство по документированию прикладных систем на основе ЭВМ

Примечание - До прямого применения данных международных стандартов в качестве государственных стандартов Российской Федерации они могут быть получены по запросам из ВНИИКИ Госстандарта России.

3 Определения

В настоящем стандарте применяют следующие термины.

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

3.2 документация: Набор из одного или более связанных документов.

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

4 Роль руководителей

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

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

1) руководящая обязанность по документированию.

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

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

Для этого требуется руководство и стимулирование персонала при проведении требуемого документирования и обеспечение его ресурсами для содействия в данной работе;

3) признаки руководящих обязанностей и поддержки.

Для этого требуется обеспечить:

а) опубликованные официальные отчеты о стратегии документирования;

б) стандарты и руководства, определяющие все аспекты документирования программного обеспечения;

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

г) выделение соответствующих ресурсов для документирования;

д) планирование документирования, осуществляемое как неотъемлемая часть процесса разработки программного обеспечения;

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

5 Функции программной документации

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

Программную документацию можно рассматривать как имеющую шесть основных функций:

1) информация для управления (см. 5.1);

2) связь между задачами (см. 5.2);

3) обеспечение качества (см. 5.3);

4) инструкции и справки (см. 5.4);

5) сопровождение программного обеспечения (см. 5.5);

6) исторические справки (см. 5.6).

5.1 Информация для управления

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

5.2 Связь между задачами

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

В типовом варианте:

специалисты в предметной области начинают проект;

аналитики формулируют требования к системе;

проектировщики разрабатывают системный и программный проекты;

специалисты по изданиям создают пользовательскую документацию в соответствии со стратегией и стандартами по документированию;

специалисты по обеспечению качества и ревизоры оценивают общую полноту и качество функционирования программного обеспечения;

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

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

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

5.3 Обеспечение качества

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

5.4 Инструкции и справки

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

5.5 Сопровождение программного обеспечения

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

5.6 Исторические справки

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

6 Установление стратегии документирования

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

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

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

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

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

2) документирование должно быть управляемым.

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

3) документация должна соответствовать ее читательской аудитории.

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

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

Процесс разработки должен быть определен;

5) должны быть определены и использованы стандарты по документированию.

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

6) должны быть определены средства поддержки.

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

7 Определение стандартов и руководств по документированию

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

модели жизненного цикла программного обеспечения;

типов и взаимосвязей документов;

содержания документа;

качества документа;

форматов документа;

обозначения документа.

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

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

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

какие типы документов требуются?

каков объем представляемой документации?

что документы содержат?

какой уровень качества будет достигнут?

где документы будут созданы?

как документы будут храниться, сопровождаться и обращаться?

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

7.1 Выбор модели жизненного цикла программного обеспечения

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

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

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

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

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

1) документация разработки (см. 7.2.1);

2) документация продукции (см. 7.2.2);

3) документация управления проектом (см. 7.2.3).

7.2.1 Документация разработки

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

Разработка документов преследует пять целей:

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

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

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

4) они образуют основу документации сопровождения программного обеспечения, требуемой сопровождающими программистами как часть документации продукции;

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

анализы осуществимости и исходные заявки;

спецификации требований;

спецификации функций;

проектные спецификации, включая спецификации программ и данных;

планы разработки;

планы сборки и тестирования программного обеспечения;

планы обеспечения качества, стандарты и графики;

защитная и тестовая информация.

7.2.2 Документация продукции

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

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

1) она обеспечивает учебную и справочную информацию для любого использующего или эксплуатирующего программную продукцию;

2) она облегчает программистам, не разрабатывавшим программное обеспечение, его сопровождение и модернизацию;

3) она помогает продаже или приемке программной продукции.

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

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

операторов, которые "прогоняют" программное обеспечение на вычислительной системе;

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

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

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

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

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

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

учебные руководства;

справочные руководства и руководства пользователя;

руководства по сопровождению программного обеспечения;

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

7.2.3 Документация управления проектом

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

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

отчеты о согласованных изменениях программного обеспечения;

отчеты о решениях, связанных с разработкой;

распределение обязанностей.

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

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

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

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

1) качество содержания можно измерять в элементах точности, полноты и ясности;

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

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

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

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

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

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

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

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

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

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

заглавие документа;

ссылочный номер документа;

номер версии документа;

дату выпуска и пересмотра;

реквизиты автора;

реквизиты утвердившего лица;

обозначение защищенности (авторских прав);

обозначение организации.

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

8 Установление процедур документирования

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

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

планирование;

подготовка;

конфигурационное управление;

проверка;

утверждение;

производство;

хранение;

дублирование;

распространение и модернизация;

продажа.

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

9 Распределение ресурсов для документирования

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

персонал (см. 9.1);

средства (см. 9.2);

финансирование (см. 9.3).

9.1 Персонал

Для процесса разработки программного обеспечения необходимы люди со знанием:

программирования - для разработки программного обеспечения;

сути предмета - для представления информации о применениях программного обеспечения;

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

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

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

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

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

9.2 Средства

Важно предусмотреть обеспечение задач документирования соответствующими и подходящими средствами.

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

9.3 Финансирование

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

10 Планирование документирования

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

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

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

План должен включать в себя изложение:

общей структуры документации;

типов и содержания документов;

качества и форматов документов;

обозначения документов;

комплектности и хранения документов;

обращения документов;

графика документирования.

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

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

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

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

редактирования при внесении комментариев, появившихся при проверке;

проведения согласования;

перевода (например, с японского на французский);

распространения.

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