Т. А. Панюкова
ДОКУМЕНТИРОВАНИЕ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ
В помощь техническому писателю
Рекомендовано
Научно-методическим советом по информатике Министерства образования и науки РФ (Челябинское отделение) в качестве учебного пособия для студентов направления «Прикладная математика и информатика»
URSS
МОСКВА
ББК 32.811 32.973-018 73
Паню ко ва Татьяна Анатольевна
Документирование программного обеспечения: В помощь техническому писателю: Учебное пособие. — М.: Книжный дом «ЛИБРОКОМ», 2012. — 264 с.
В учебном пособии рассказывается о важности процесса документирования, его месте в процессе создания программного средства и о работе технического писателя. Рассмотрены различные виды программной документации и существующие российские и международные стандарты, знание которых необходимо техническому писателю. В заключение приводится краткое описание современных, издательских систем и CASE-средств, используемых для создания документации различного уровня.
Книга предназначена для студентов направления «Прикладная математика и информатика» (ФГОС 3-го поколения), а также для разработчиков программных средств.
Рецензенты:
директор Института информационных технологий (ИИТ ЧелГУ),
канд. техн, наук А. В. Вохминцев’,
ведущий разработчик ООО «Прикладные технологии» (г. Челябинск)
С. В. Ермаков
Издательство «Книжный дом “ЛИБРОКОМ”».
117335, Москва, Нахимовский пр-т, 56.
Формат 60x90/16. Печ. л. 16,5. Зак. № ЖС-30.
Отпечатано в ООО «ЛЕНАНД».
117312, Москва, пр-т Шестидесятилетия Октября, 11А, стр. 11.
ISBN 978-5-397-02930-8
© Книжный дом «ЛИБРОКОМ», 2012
Оглавление
Введение ................................................7
1.	О процессе документирования в ИТ-подразделении ....................................  9
1.1.	Об основных компетенциях....................... 18
1.2.	О работе технического писателя ................ 32
2.	Цели и принципы документирования программных средств..............................................       40
2.1.	Стандарты документирования программных средств................................. 41
2.2.	Технологическая и эксплуатационная документация на программное средство............................. 48
2.2.1.	Технологическая документация............. 48
2.2.2.	Эксплуатационная документация............ 50
2.2.3.	Описание программы и применения.......... 52
2.2.4.	Описание языка........................... 55
2.2.5.	Руководство администратора............... 58
2.2.6.	Руководство оператора.................... 62
2.2.7.	Руководство пользователя................. 64
2.2.8.	Руководство программиста................. 68
2.2.9.	Руководство системного администратора.... 74
2.2.10.	Справочная система...................... 79
2.3.	Организация документирования программных средств................................. 81
2.3.1.	Процесс документирования................. 83
3
4
ОГЛАВЛЕНИЕ
2.3.2.	Документирование корпоративной информационной системы........................... 88
2.3.3.	Документирование комплектуемого решения ... 90 2.4. Управление документированием
этапов жизненного цикла программного средства............................ 92
2.4.1.	План выполнения документирования.......... 93
2.4.2.	Планирование качества документов.......... 96
2.4.3.	Архитектура системы документооборота......101
2.4.4.	Конфигурационное управление
документацией .............................105
2.5.	Документация управления качеством программного средства...............................................108
2.6.	Структура и содержание документов по этапам жизненного цикла программного средства..................................112
2.6.1.	Документы предварительных требований, спецификаций и ресурсов для разработки программного средства............................113
2.6.2.	Документы процессов проектирования и выбора характеристик качества программного средства............................119
2.6.3.	Документы процессов разработки и программирования компонентов программных средств..............................124
2.6.4.	Документы верификации и тестирования компонентов программных средств..................126
2.6.5*	Документы квалификационного тестирования, испытаний и оценивания качества программных средств.....................134
2.6.6.	Документы сопровождения и конфигурационного управления версиями программного средства............................140
2.6.7.	Документы процессов эксплуатации программных средств..............................145
2.7.	Состав пользовательской документации на программное средство...............................................148
ОГЛАВЛЕНИЕ
5
2.7.1.	Предмет документирования..................150
2.7.2.	Комплект документации. Документ...........150
2.7.3.	Формальная структура документа............152
2.7.4.	Типы информации в документе...............152
2.7.5.	Изложение материала в сплошном тексте.....153
2.7.6.	Слова и формулировки......................156
2.7.7.	Авторская разметка текста.................157
2.8.	Техническое задание на проектирование ..................................  158
2.8.1.	ГОСТ 19.201-78. Техническое задание.
Требования к содержанию и оформлению.......160
2.8.2.	Простейший пример технического задания .... 164
2.8.3.	Пример технического задания
на электронный ресурс......................169
2.9.	Эскизный, технический, рабочий проект программного средства..........................182
2.10.	Документация тестирования компонентов и комплексов программ.....................185
2.11.	Документация сопровождения и конфигурационного управления версиями программ.....................................195
2.11.1.	Единицы конфигурационного управления.....197
2.11.2.	Управление версиями......................199
2.11.3.	Управление сборками......................201
2.11.4.	Понятие baseline.........................203
2.11.5.	Стандартизация процесса управления конфигурацией ...................................204
3. Пакеты программ для формирования отчетов..............................  210
3.1.	Особенности работы в Microsoft Word и Open Office для технического писателя..............................................214
3.1.1.	Рекомендации по использованию стилей......215
3.1.2.	Особенности оформления рисунков...........219
3.1.3.	Прочие рекомендации ......................221
3.2.	Экскурс в историю: система документирования Rational SoDA........................224
6
ОГЛАВЛЕНИЕ
3.3.	Технология единого источника....................234
3.3.1.	Общие сведения о технологии единого
источника..................................235
3.3.2.	Основные понятия и определения............239
3.3.3.	Содержание, структура, оформление.........241
3.3.4.	Единый источник как база знаний...........244
3.3.5.	Технологическая платформа DocBook/XML . . . 245
3.3.6.	MadCap Flare: система
для разработки технической документации на основе единого источника..................................247
3.3.7.	Arbortext: система разработки, генерации и публикации технической документации.....................................251
3.4.	Издательская система ...........................256
Литература..........................................    261
Введение
Учебное пособие является подробной реферативной подборкой материалов, так или иначе связанных с процессом документирования программного средства. Дело в том, что информация по данному вопросу рассредоточена по огромному числу источников, и до сих пор не было издано ни одного пособия для технического писателя.
Все вопросы программной инженерии, проектирования и организации работы над сложнымии программными средствами освещены во второй части пособия < Проектирование программных средств».
Данная книга не является руководством пользователя по той или иной программе, в ней описывается только процесс документирования, его основные этапы. В первой части рассказывается о процессе документирования и его месте в работе IT-подразделения, о работе технического писателя. Во второй части подробно рассматриваются различные виды программной документации и существующие российские и международные стандарты, знание которых необходимо техническому писателю. В третьей части приводится описание различных современных издательских систем, используемых для создания документации различного уровня. Учебное пособие является навигатором в области документирования программ и позволит читателю найти все требуемые документы, обозначить содержание того или иного документа, выбрать издательскую систему для дальнейшей работы с документацией.
В тексте приведены примеры оглавлений некоторых документов, их краткое содержание и т.д.
Очевидно, что рассматриваемые в данном пособии принципы документирования программного средства никогда не будут реализованы: описывается идеальная и самая сложная ситуация. Если руководство-
7
8
ВВЕДЕНИЕ
вагься абсолютно всеми данными, приведенными в учебном пособии, при создании достаточно простой программы, можно оказаться попросту погребенным под кипой никому не нужных руководств и документаций. Следование абсолютно всем рекомендациям учебного пособия приемлемо для создания крупномасштабных проектов. В остальных случаях рекомендуется в первую очередь руководствоваться правилами здравого смысла и создавать только те документы, в которых есть необходимость.
Но главная идея документирования заключается в постулате: «Программы пишутся для людей, а не для себя любимого!»
Список часто встречающихся сокращений
•	ИС - информационная система;
•	ИТ - информационные технологии;
•	ЕСКД - единая система конструкторской документации;
•	ЕСПД - единая система программной документации;
•	ЖЦ - жизненный цикл;
•	ПО - программное обеспечение;
•	ПС - программное средство;
•	ЭД - эксплуатационная документация;
•	СВТ - средства вычисительной техники;
•	ТЗ - техническое задание;
•	ПК - персональный компьютер;
•	УК - управление конфигурацией.
1. О процессе документирования в ИТ-подразделении
Чукча не хочет быть читатель, чукча хочет быть писатель...
(Анекдот)
Принято считать, что практически каждый поставщик независимо от вида деятельности обязан комплектовать свою продукцию (или свой сервис) технической документацией. Заказчиком такой работы обычно выступает ИТ-подразделение крупного или среднего предприятия. В зависимости от целей и охвата она может быть непосредственно инициирована ИТ-директором или менеджером, ответственным за какой-то участок, например за определенную автоматизированную систему. Цели, преследуемые при документировании ИТ-инфраструктуры, как правило, таковы [16]:
•	обеспечить правильную работу сотрудников предприятия с программами, сервисами, автоматизированными системами;
•	снизить нагрузку на службу поддержки пользователей («service desk»);
•	сократить сроки восстановления работоспособности всех сервисов и систем в случае сбоев или разрушения;
•	обеспечить преемственность эксплуатации всех ИТ-ресурсов при ротации инженерно-технического персонала ИТ-подразделения;
•	обеспечить необходимой технической информацией подрядные организации, в том числе, системных интеграторов и сервисные компании;
•	организовать учет ИТ-активов и автоматизировать формирование отчетов об их составе и состоянии;
•	сделать работу ИТ-подразделения более прозрачной и понятной для менеджмента предприятия.
9
10
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
Редкое решение не имеет документации вовсе, однако, доступная документация далеко не всегда в полной мере отвечает потребностям компании. В частности, типичны следующие обстоятельства [16].
Документирование внутренних разработок выполняется программистами или техническими менеджерами по остаточному принципу, в итоге техническая документация оказывается неполна и зачастую невнятна. При постепенном внесении изменений в программу или автоматизированную систему накапливается отставание документации от действительности.
Документация на приобретаемые программные средства разрабатывается из общих соображений, она не отражает реалий работы в конкретной организации. Практика применения приобретенной программы складывается в компании стихийно, каждый сотрудник знает свой участок работы, обучение новичков возможно только из <уст в уста» [16].
Документация на заказные программы и автоматизированные системы, как правило, создается в условиях жестких сроков, что не лучшим образом отражается на ее качестве. Причем стоит учитывать и высокую загрузку представителей заказчика на стадии ввода решения в эксплуатацию. Работа по модификации заказного решения нередко распределяется между собственными сотрудниками ИТ-департамента и компанией-поставщиком. В этом случае техническая документация либо оказывается за пределами чьей бы то ни было зоны ответственности, либо развивается в двух параллельных несовпадающих версиях.
Отсутствие полноценной технической документации ведет к:
•	издержкам и проволочкам, связанным с ошибками в работе сотрудников,
•	появлением постоянно перегруженных незаменимых людей как в ИТ-департаменте, так и среди бизнес-пользователей,
•	повышенным количеством обращений в службу поддержки пользователей.
Без технической документации затруднено взаимодействие с аутсорсерами, будь то консультанты, системные интеграторы или сервисные компании. Для территориально распределенных организаций сказанное выше приобретает особое значение, поскольку передача технической информации между сотрудниками удаленных офисов в рабо
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
11
чем порядке существенно затруднена. Наконец, в компаниях, с которыми клиенты и партнеры взаимодействуют через ИТ-инфраструктуру (банки, платежные системы, телекоммуникационные провайдеры, системы резервирования билетов, интернет-магазины), техническая документация, а также служба поддержки, качество работы которой во многом зависит от технической документации, становится частью продукта или услуги и, следовательно, фактором, непосредственно влияющим на их конкурентоспособность.
Все это и вынуждает ИТ-департаменты выделять документирование в самостоятельное направление работы, учитывать его при формировании бюджета и планировании загрузки своих специалистов.
В дальнейшем будем рассматривать типичные (не идеальные ситуации), описывать реальную практику (не предписания, какой она должна быть). Например, разработка технологических инструкций (регламентов) должна выполняться до ввода автоматизированной системы в промышленную эксплуатацию. Однако во многих случаях она выполняется после. Такое положение дел можно объявить неправильным, ссылаясь на ГОСТы, ITIL и прочие источники. Но подобное положение дел регулярно складывается в различных компаниях, значит, существуют некоторые достаточно веские причины, которые не могут быть исчерпаны в короткие сроки. Следовательно, ИТ-департаментам необходимы действенные способы решения проблем с документацией.
С другой стороны, было бы неверно рассматривать документирование в ИТ-департаментах исключительно как паллиатив, компенсирующий проявления организационных болезней. Это важный фактор развития ИТ-инфраструктуры, необходимый, но не достаточный инструмент для расширения ее возможностей. Если речь идет о крупной организации, ИТ-инфраструктура сама является сложной системой, объединяющей многочисленные компоненты, по-разному устроенные и включенные в нее в разное время [16]. Даже если каждый компонент ИТ-инфраструктуры идеально и своевременно документирован в отдельности, поддержание в рабочем состоянии всей инфраструктуры, тем более, совершенствование (например, интеграция приложений), требует достоверных, полных и непротиворечивых сведений об их составе, доступности, взаимосвязях между ними, используемых форматах данных, интерфейсах, протоколах. Сведения эти нужно не только хранить, но и уметь оперативно их извлекать и профилировать. Например, получение перечня приложений, работающих с данными о
12
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
клиентах, не должно требовать сквозного просмотра многочисленных томов. Отсюда следует потребность в формировании объединенной документации (а также метадокументации) и автоматизации работы с ней.
В живой организации ИТ-инфраструктура постоянно претерпевает изменения, из-за этого она всегда до некоторой степени рассогласована. Рассмотрим следующую ситуацию: пока ИТ-специалисты заняты стратегическим проектом по замене группы локальных систем общей ERP-системой или по внедрению интеграционной шины, функциональные подразделения - маркетинг, продажи, логистика и др. -автоматизируют себя сами в меру сил и возможностей. К сожалению, так называемая лоскутная автоматизация неизбежна, поскольку задачи, требующие срочного решения, не иссякают.
Корпоративная ИТ-инфраструктура растет гигантскими темпами: сначала занимаются новые территории, потом ассимилируются, включаются в общую жизнь. Возникает вопрос: что лучше, переделывать (а в крайнем случае заменять) уже созданные кем-то локальные решения, или интегрировать их в общую среду? На этот счет есть разные мнения, но если предполагается интеграция, то ее возможность должна быть обеспечена соблюдением определенных корпоративных стандартов. Они же базируются на технической документации, и во многом устроены, как техническая документация.
Каким бы ни было техническое устройство ИТ-инфраструктуры, она связывает между собой живых людей. Для того чтобы они могли работать с ней, им необходима техническая информация. Собирать, систематизировать, излагать и доставлять ее по адресу - функция документирования в ИТ-департаменте.
Предметы документирования и состав комплекта эксплуатационной документации (ЭД) на каждый из них приведены в табл. 1.1. В таблице перечислены не все возможные документы, и даже не все обязательные, а наиболее важные содержательно. В зависимости от того, является ли программный продукт приобретенным или разработан силами организации, его документирование может быть необходимо в разном объеме.
В любом случае полезно завести формуляр, фиксирующий наличие программного продукта в организации. Все формуляры вместе взятые образуют каталог программного обеспечения, имеющегося в распоряжении организации. Общее описание программного продукта содер-
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
13
Таблица 1.1. Предметы документирования и комплекты ЭД
Предмет	Документация
Программный продукт	-	паспорт -	общее описание -	руководство системного администратора -	руководство пользователя -	руководство программиста -	формуляр
Средства вычислительной техники	- паспорт - руководство - формуляр
Сервис	- регламент использования - формуляр
Автоматизированная система	-	паспорт -	ведомость эксплуатационных документов -	общее описание системы -	описания бизнес-процессов -	технологические инструкции -	руководство пользователя -	электронная справка -	эксплуатационная документация на программные и аппаратные компоненты системы -	формуляр
ИТ-инфраструктура в целом	-	каталог технической документации -	отчеты о состоянии и динамике ИТ-активов -	карта информатизации -	стандарты организации в сфере ИТ -	ИТ-стратегия
14
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
жит сведения о его функциональности и составе. Этот документ адресован, в первую очередь, лицам, принимающим решения о применении программного продукта в тех или иных целях.
Руководство системного администратора содержит сведения, необходимые для установки программных модулей, входящих в состав программного продукта, а также их интеграции друг с другом и внешним программным обеспечением, например с сервером баз данных или НТТР-сервером.
Руководство пользователя содержит подробное описание всех функций, реализованных в программном продукте, дает четкие указания по решению наиболее типичных пользовательских задач. Оно касается работы автоматизированной системы с программным обеспечением. Оно разъясняет технику решения элементарных задач, с которыми сталкивается пользователь.
Руководство программиста описывает техническое устройство программ, входящих в состав программного продукта. В зависимости от ситуации оно может быть адресовано разработчикам, осуществляющим его сопровождение, настройку для решения конкретных прикладных задач или интеграцию с другими приложениями. В руководстве программиста могут быть описаны программные интерфейсы, реализуемые алгоритмы, структура базы данных, форматы экспортируемых и импортируемых файлов.
Маркетинговая документация разрабатывается в том случае, когда для приложения необходимо предоставить рекламные материалы, чтобы заинтересовать людей, обратив их внимание на продукт. Такая форма документации разрабатывается целью:
•	подогреть интерес к продукту у потенциальных пользователей;
•	информировать их о том, что именно делает продукт, с тем, чтобы их ожидания совпадали с тем что они получат;
•	объяснить положение продукта по сравнению с конкурирующими решениями.
Одна из хороших маркетинговых практик - предоставление слогана, простой запоминающейся фразы, иллюстрирующей мысль, которую производитель хотел бы донести до пользователя, а также характеризующей ощущение, которое создает продукт.
Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем все остальное.
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
15
Более подробно о составе документации будет рассмотрено в следующих разделах.
Еще одним объектом для документирования являются средства вычислительной техники (СВТ). Под СВТ в данном случае понимаются различные устройства: серверы, компьютеры на рабочих местах пользователей, сетевые и периферийные устройства. Их документирование выполняется с двоякой целью:
•	инвентаризация, оценка текущего состояния парка СВТ, прогнозирование потребности в пополнении и ремонте;
•	дальнейшее описание развертывания сервисов и автоматизированных систем, выявление зависимости их работоспособности от состояния конкретных устройств.
Как правило, организации приобретают готовые устройства, а не производят их для собственных нужд, поэтому необходимость в разработке паспорта и руководства по эксплуатации возникает редко. Если руководство по эксплуатации поставляется на иностранном языке, может потребоваться его перевод, в особенности это касается принтеров, сканеров, различных терминалов и других устройств, которыми приходится иметь дело не только ИТ-специалистам, но и остальным сотрудникам организации.
Формуляр устройства фиксирует цели его использования в организации, физическое расположение и параметры конфигурации. Также в формуляре могут проставляться отметки о ходе эксплуатации: дата ввода в эксплуатацию, сведения о сбоях, ремонтах, сроках профилактического технического обслуживания. Все формуляры вместе взятые служат исходным материалом для инвентаризации СВТ.
Программные средства, функционирующие на компьютерах организации (или получаемые в порядке аренды) и допускающие обращение к их функциональности со стороны пользователей, принято называть сервисами. Они могут быть:
•	прикладными (общие папки на сервере, сетевые принтеры, портал для сотрудников организации);
•	системными (серверы баз данных, почтовые серверы и т.п.).
Формуляр сервиса фиксирует цели его использования в организации, содержит сведения и его развертывании и параметрах конфигурации. Также в формуляре могут проставляться отметки о ходе экс-
16
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
плуатации сервиса: дата ввода в эксплуатацию, сведения о сбоях, переустановке, изменениях конфигурации.
Немаловажно, что автоматизированная обработка формуляров сервисов (например, при их ведении с помощью конфигурационной базы данных, см. ниже) позволяет прослеживать зависимости между прикладными системами, сервисами и средствами вычислительной техники. Отчеты о зависимостях позволяют сократить поиск возможных источников проблем при сбоях в работе прикладных систем и сервисов.
Регламент использования сервиса определяет принятые в организации правила, по которым осуществляется предоставление доступа к этому сервису и работа с ним.
Разработка эксплуатационной документации на автоматизированную систему - одна из наиболее часто встречающихся на практике задач. Она актуальна как для систем, вводимых в эксплуатацию, так и для систем, уже функционирующих на протяжении определенного времени. Подробнее об эксплуатационной документации см. раздел 2.2..
В первую очередь, документация необходима для правильной организации работы сотрудников предприятия с автоматизированной системой. Дело в том, что документации, которую поставляют разработчики системы, часто оказывается далеко не достаточно. Тем более, невозможно обойтись документацией, поставляемой разработчиками тиражируемых программных продуктов, поскольку в ней не учтены (и не могут быть учтены) процессы конкретного предприятия.
Документация, адресуемая непосредственно пользователям системы, включает в себя три уровня:
•	описания процессов;
•	технологические инструкции;
•	руководство пользователя.
Описания процессов показывают порядок работы в целом. Как правило, процесс связан с достижением некоторого полезного, осмысленного вне организации (или какого-то ее подразделения) результата: продажи товара клиенту, закупки партии товара у поставщика, открытия лицевого счета клиенту банка, подготовки бухгалтерского баланса и т.п. Конечно, не всякий сотрудник предприятия действительно нуждается в описании процесса, многим вполне достаточно знать собственный участок работы. Однако описание процесса, особенно, если
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
17
оно выполнено в хорошо обозримой табличной или графической форме, служит своего рода оглавлением, средством навигации по описаниям отдельных операций. Оно помогает быстрее найти в документации нужные сведения и способствует лучшему их пониманию.
Технологическая инструкция адресована сотруднику, играющему определенную роль в процессе или занимающему определенное место в организационной структуре предприятия. Так, может быть технологическая инструкция менеджера по продажам, операциониста, бухгалтера. Технологическая инструкция описывает порядок выполнения этим сотрудником каждой из свойственных ему операций. Под операцией при этом понимается действие, осмысленное вне зависимости от технического средства его выполнения и приводящее к определенному значимому результату. Например, выставление клиенту счета, размещение заказа у поставщика, перемещение товара с одного склад на другой - это операции. Необходимость их выполнения диктуется жизнью, эти действия в соответствующих ситуациях пришлось бы совершить независимо от того, как они автоматизированы и автоматизированы ли вообще.
Если технологическая инструкция предписывает в определенной ситуации создать накладную, заполнить в ней опеделенные поля, а затем вывести ее на печать, то руководство пользователя говорит о том, как именно, с помощью каких пунктов меню, экранных форм, ккнопокн» это сделать.
Описание процесса содержит ссылки на технологические инструкции, технологические инструкции содержат ссылки на руководство пользователя. Чтобы ссылками было удобно пользоваться, описания процессов, описания операций и описания пользовательских задач сводятся вместе в гипертекстовой электронной справке. Ее можно разместить на корпоративном портале и предоставить к ней доступ сотрудникам организации. Вместе с тем, отдельные описания процессов, технологические инструкции и руководства можно хранить в общедоступном формате (например, PDF или Microsoft Word), выводить на печать, включать в официальный документооборот предприятия, проставлять на них утверждающие подписи, в общем, обращаться с ними как с традиционными документами.
Документы, описывающие различные компоненты ИТ-инфраструктуры, во многих случаях прямо или косвенно ссылаются друг на друга. Кроме того, они в значительной степени основаны на
18
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
одной и той же информации, которая по-разному в зависимости от аудитории и задач каждого документа структурируется и подается с разной степенью подробности.
Например, в формуляре сервера последний рассматривается сам по себе, а в документации на автоматизированную систему - как часть комплекса технических средств. В руководстве пользователя программный продукт рассматривается сам по себе, а в формуляре сервера только упоминается, поскольку он установлен с целью создания в сети сервиса на основе этого программного продукта.
При такой насыщенности явными и неявными связями разработка и сопровождение каждого документа в отдельности становится чрезвычайно трудоемкой задачей, поскольку изменения, произошедшие с одним из компонентов, нередко требуют отражения в нескольких документах, в том числе, входящих в сферы ответственности разных людей. Если вести эту работу вручную, то исправленные версии документов будут ощутимо запаздывать и содержать расхождения между собой.
Для автоматизации документирования ИТ-инфраструктуры применяется конфигурационная база данных, которая позволяет вводить, хранить и модифицировать данные о каждом компоненте ИТ-инфраструктуры и его взаимосвязях с другими компонентами. Документы при этом рассматриваются как отчеты, формируемые на основе конфигурационной базы. После внесения изменений в конфигурационную базу данных их можно сформировать автоматически по предусмотренным для них шаблонам.
1.1.	Об основных компетенциях
Афоризмы пропускют подробности и выделяют главное.
Это превосходная документация высокого уровня.
(Алан Дж.Перлис)
Постановка задачи по подготовке комплекта технической документации для программного средства предполагает ответ на следующий ключевой вопрос [29]: «Какой цели должна служить документация?» Формально техническая документация к программному сред
1.1. ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
19
ству имеет общую цель - предоставить техническую информацию о программном средстве тем, кто нуждается в этой информации. При этом у всякой документации есть одна или несколько частных целей, которые необходимо учитывать при постановке задачи.
Частными целями являются, например, следующие:
•	способствование удобной и корректной эксплуатации программного средства;
•	обеспечение соответствия технической документации определенному стандарту;
•	снабжение пособием сотрудников службы технической поддержки;
•	предоставление необходимой информацией для интеграции программного средства с другими программными средствами.
От частных целей, которые призвана решить документация, зависит расстановка приоритетов в дальнейшей работе над документацией. Ими в значительной степени определяется и состав комплекта документации, и характер изложения, и критерии качества. Например, если целью документации является содействие пользователю в освоении программного средства, особое внимание уделяют подготовке руководства пользователя, а в нем - легкости восприятия текста, удобному расположению материала, наличию необходимого иллюстративного материала и вспомогательного аппарата. Если документация в первую очередь должна отвечать определенному стандарту, сосредотачиваются на комплектности документации и соответствии содержания и оформления документов требованиям стандарта.
Иногда различные документы, входящие в один комплект документации, преследуют разные цели: одни служат для удобства пользователя, другие, другие - для удобства специалистов по техподдержке. Третьи обеспечивают полноту стандартного комплекта.
Какому стандарту должна соответствовать документация? Создание документации к программным средствам может регулироваться различными системами стандартов: ГОСТ, ISO, принятых корпоративных стандартов, отраслевых стандартов и т.д. Стандартом обычно определяются:
•	модель жизненного цикла программного средства;
•	состав документов, создаваемых на каждой стадии;
•	состав и структура каждого из документов.
20
L О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
Тот или иной стандарт выбирается:
•	по технологическим соображениям (весь процесс разработки программного средства подчинен определенной системе стандартов);
•	по административным соображениям (заказчик или партнер-смежник требуют соблюдения той или иной системы стандартов).
В первом случае документирование сопровождает весь процесс разработки программного средства.
Во втором случае документация составляется задним числом. Состав комплекта документации, состав и структура каждого из документов отвечают стандарту, диктуемому внешней инстанцией. При этом они не всегда соответствуют той модели жизненного цикла программного средства, которая в действительности принята разработчиками.
Если ни технологическими, ни административными соображениями не диктуется никакой стандарт, стандарт общего образца позволяет поддерживать необходимый уровень унификации и технической культуры.
Кто является потенциальным читателем документации? В комплект документации входят документы разного назначения. Они могут быть адресованы читателям с разной компетенцией и разным отношением к программному средству. Адресатом того или иного документа может быть разработчик программного средства, сотрудник службы поддержки, пользователь (оператор) и т.д. Часто это прямо указано в названии документа.
При постановке задачи особое внимание уделяют адресату эксплуатационной части документации - пользователю или оператору. Изучаются его профессиональные знания, навыки использования компьютерной техники и программных средств, условия работы. Принимаются решения о включении в состав эксплуатационной документации той или иной дополнительной информации, а также о степени подробности изложения.
Какие требования качества предъявляются к документации? Требования к документации, не предусмотренные стандартом, обязательно оговариваются на стадии постановки задачи. При разработке технической документации учитываются требования двух видов.
L1. ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
21
•	Общеобязательные требования: орфографическая и стилистическая грамотность, минимальная техническая культура, единство отраслевой и компьютерной терминологии.
•	Дополнительные требования: подробность изложения, полнота изложения, строгость подачи информации, наглядность, обучающие качества и т. д.
Общеобязательные и дополнительные требования подробно обсуждаются со всеми заинтересованными сторонами. На основе обсуждения формируется документ «Требования к технической документации». Он включает в себя стандарт, которому должна соответствовать документация, список документов, включаемых в комплект, а также общеобязательные и дополнительные требования к качеству документации.
Постановка задачи по написанию технической документации является частью постановки задачи разработки программного средства и фиксируется в документации на том этапе и таким образом, как это предусмотрено выбранным стандартом и моделью жизненного цикла программного средства.
Организация работы над технической документацией к программному средству предполагает ответ на следующие вопросы [29].
Кому поручается непосредственное выполнение работы? Техническую документацию непосредственно создает специалист, которого принято называть техническим писателем.
Им может являться сотрудник корпорации, совмещающий обязанности технического писателя с другими служебными обязанностями. Программист, сотрудник службы технической поддержки, бета-тестер и т. д. На начальных стадиях жизненного цикла те или иные документы могут подготавливаться непосредственно членами команды разработчиков. Составление рабочей (эксплуатационной, пользовательской) документации им обычно не поручается.
Обязанности технического писателя может выполнять и специально выделенный для этого член команды разработчиков. Включение в команду разработчиков технического писателя практикуется при проектировании достаточно компактных программных средств (например, «коробочных» продуктов). Технический писатель - это особая профессия, требующая определенных профессиональных знаний и навыков, поэтому сотрудник проходит специализированный тренинг. Подробней об этой профессии см. в следующем разделе.
22
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
В качестве технического писателя может выступать и сотрудник или сотрудники отдела технической документации. Этот отдел организуется в корпорации в том случае, если необходимо постоянное документационное сопровождение масштабного программного средства: подготовка новых документов, тестирование, сопровождение и корректировка старых и т. д.
Кроме того, возможно привлечь и внешних исполнителей. Это обычно сотрудник специализированной компании (поставщика услуг в области технических коммуникаций). Он исходно обладает требуемой квалификацией. Если составление документации поручено внешнему исполнителю, особое значение приобретает правильная организация рабочего процесса.
Как распределяются основные обязанности? Основные обязанности распределяются следующим образом.
•	Исполнитель. Технический писатель или группа технических писателей.
•	Консультант. Обычно выделяется один или несколько разработчиков и/или сотрудников службы технической поддержки, которые дают техническим писателям необходимую информацию о программном средстве, отвечают на вопросы, разъясняют сложные аспекты функционирования и т. д.
•	Тестировщик. Один или несколько сотрудников, которые проверяют техническую документацию на предмет ее соответствия программному средству.
•	Редактор. Сотрудник, занятый проверкой технической документации с точки зрения соблюдения принятых стандартов и критериев качества.
•	Верстальщик. Сотрудник, занятый версткой бумажных и/или электронных публикаций. Если верстка минимальна или в значительной степени автоматизирована, роль верстальщика исполняет сам технический писатель. Для подготовки качественных публикаций необходима работа профессионального верстальщика.
•	Корректор.
•	Ответственный приемщик. Должностное лицо в корпорации, принимающее решение о готовности документации и ее соответствии требованиям.
1.1. ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
23
Взаимодействие между этими инстанциями планируется заранее и может существенным образом варьироваться.
Если постоянная рабочая группа из квалифицированных технических писателей закреплена за определенным проектом, обязанности тестера и редактора оттесняются на второй план и носят вспомогательный характер.
Если масштабная многокомпонентная разработка требует периодического наращивания ресурсов для подготовки технической документации, центральное место занимает координационный орган - редакция. Туда поступают запросы на выполнение определенного объема работы. Редактор распределяет заказы между техническими писателями и затем принимает у них выполненную работу. Таким образом, редакция контролирует как распределение заказов, так и качество выполненной работы.
Как работа над технической документацией привязана к жизненному циклу программного средства? Работа над технической документацией может выполняться как на тех или иных стадиях жизненного цикла, так и на стадии внедрения или сопровождения.
В первом случае работа технического писателя выполняется параллельно с разработкой программного средства. Подготовка тех или иных документов является составной частью тех или иных стадий жизненного цикла. При такой организации работы создается полный комплект документации.
Во втором случае работа технического писателя выполняется задним числом. Такая организация работы используется и в тех случаях, когда необходима только эксплуатационная документация, и в тех случаях, когда заказчик или партнер требует полного комплекта документации, предусмотренного тем или иным стандартом.
Как работа над технической документацией организована во времени? Работа над технической документацией может организована во времени двумя способами.
•	Срочная работа. Работа начинается в определенный момент времени и должна быть завершена к определенному сроку. Срок окончания может быть оговорен не вполне жестко, допускать переносы и продления, тем не менее планируется завершение работы в определенный срок. Внешний исполнитель в этом случае привлекается к работе на основе срочного заказа.
24
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
•	Постоянное сопровождение. Работа над документацией продолжается в течение определенного периода. В течение этого периода постоянно ведутся работы по созданию и обновлению документации.
Внешний исполнитель в этом случае привлекается к работе на основе абонентского обслуживания. Организация работы над технической документацией находит отражение в договоре с внешним исполнителем.
Программное обеспечение для подготовки технической документации выбирается исходя из состава комплекта документаций, требований к нему, особенностей организации рабочего процесса.
Среди технологических цепочек, используемых для работы над технической документацией, можно упомянуть наиболее часто встречающиеся.
Microsoft Word — PDF. Текст пишется с использованием текстового редактора Microsoft Word (в составе Microsoft Office) и затем конвертируется в формат PDF. Технологическая цепочка позволяет готовить бумажные публикации (а также комплекты электронной документации в формате PDF).
Программа используется в тех случаях, когда требования к издательскому качеству документации не высоки. Достоинствами являются легкость внедрения и возможность рецензирования и редактирования материалов всеми, кто получает к ним доступ. Недостатком является невысокое качество верстки.
Adobe FrameMaker — PDF. Текст верстается с использованием программного комплекса Adobe FrameMaker, созданного для технических специалистов, и затем конвертируется в формат PDF. Технологическая цепочка позволяет готовить бумажные публикации (а также комплекты электронной документации в формате PDF). Возможно также преобразование в другие форматы (RTF, HTML, различные приложения XML и т. д.).
Используется для подготовки публикаций профессионального издательского качества.
Впервые появившийся в восьмидесятые годы пакет FrameMaker компании Frame Technologies остается и по сей день одним из лучших инструментов для верстки длинных и сложно организованных документов. Первоначально программа готовилась для работы на Unix-станциях для создания объемных индексированных томов, например
1.1. ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
25
технических описаний самолетов или военного снаряжения, а также для верстки текстов, требующих частого обновления, документации к программному обеспечению [7].
Сегодня Adobe FrameMaker 10 представляет собой мощное решение для создания авторского контента и публикации техническими специалистами [44]. Он позволяет воспользоваться преимуществами интуитивного пользовательского интерфейса, универсальных рабочих процессов и сред разработки авторского контента на основе шаблонов для упрощения публикации контента и соблюдения организационных требований к согласованности и фирменному оформлению. Программа поставляется с утилитами Acrobat Distiller и Reader, а также содержит средства для работы с Internet, позволяющие экспортировать файлы в форматы PDF и HTML, для чего достаточно выбрать соответствующую опцию в диалоговом окне < Сохранить как» (Save As). Поскольку в последнее время компании все чаще и чаще готовят учебные курсы или инструкции, обычно являющиеся объемными документами, для размещения в корпоративных intranet- и extranet-сетях, поддержка форматов Inetrnet становится необходимой функцией пакетов для верстки.
Основные приемы ввода текста, принятые в программе, отличаются от способов работы с текстом в таких редакторах, как, например, Microsoft Word. FrameMaker не разбивает страницу на строчки; текст размещается отдельными фрагментами в специальных хранилищах -текстовых блоках или, как их иногда называют, фреймах (frames). Текстовый блок - это своеобразный контейнер произвольных размеров, который может находиться в любом месте страницы. Блоки могут соединяться друг с другом, образуя так называемые текстовые цепочки.
К недостаткам относится необходимость затрат на внедрение и невозможность редактирования материалов «на лету». Еще одной подобной программой от фирмы Adobe, используемой для верстки документов, является InDesign.
Однако эти два продукта фирмы Adobe обладают одним существенным недостатком. Ориентируясь на объектную организацию информации на странице, на профессиональный дизайн получившегося документа, они очень неудобны в использовании при внушительной цене на лицензионную копию (актуальные цены на ПО Adobe можно узнать на официальном сайте [44]).
26
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
Технологии подготовки контекстной справки. Технологические цепочки этого типа используются для создания контекстной справки в одном из распространенных форматов: WinHelp, HTML Help и т. д. Цепочка может включать в себя специализированную программную систему (ForeHelp, eHelp RoboHelp) или обходиться без нее.
Технологии подготовки контекстной справки требуют затрат на внедрение и согласование действий между техническим писателем и командой разработчиков.
Технология единого источника на основе DocBook. Текст технической документации изначально пишется на языке разметки DocBook и используется в качестве единого источника. Две параллельные технологические цепочки позволяют получить файл в формате PDF (который в дальнейшем распространяется в электронном виде или служит основой для бумажной публикации) или файл в формате HTML Help.
Технология единого источника на основе DocBook является оптимальным решением в тех случаях, когда необходимо составить и поддерживать техническую документацию как в форме бумажных (или электронных) документов, так и в форме системы контекстной справки. При этом все изменения вносятся в единый источник, выходные же файлы любого формата при необходимости генерируются из единого источника. Таким образом, их содержимое всегда соответствует актуальному состоянию исходного текста, написанного на DocBook.
Использование издательской системы ВТ^Х. Это наиболее популярный набор макрорасширений (или макропакет) системы компьютерной верстки ТеХ, который облегчает набор сложных документов.
Общий внешний вид документа в В-Т^Хопределяется стилевым файлом. Существует несколько стандартных стилевых файлов для статей, книг, писем и т. д., кроме того, многие издательства и журналы предоставляют свои собственные стилевые файлы, что позволяет быстро оформить публикацию, соответствующую стандартам издания.
Термин ВТеХотносится только к языку разметки, он не является текстовым редактором. Для того, чтобы создать документ с его помощью, надо набрать .tex файл с помощью какого-нибудь текстового редактора. В принципе, подойдцт любой редактор, но большая часть людей предпочитает использовать специализированные, которые так или иначе облегчают работу по набору текста ВТ^Х-разметки. Пере
1.1. ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
27
численные системы (MSWOrd,, DocBook и пр. системы) более подробно рассмотрены во второй части данного пособия.
Разработка технической документации к программному средству состоит из следующих этапов. Сбор информации о программном средстве. Технический писатель внимательно изучает материалы, предоставленные консультантами, знакомится с готовыми модулями или с программным средством в целом. При этом принимаются во внимание следующие аспекты:
•	реализованная или предполагаемая к реализации функциональность программного средства;
•	структура пользовательского интерфейса;
•	практические задачи, решаемые при эксплуатации программного средства;
•	проблемы и затруднения, которые могут возникать при эксплуатации программного средства.
Первичный сбор информации о программном средстве завершается составлением структуры документации- Дальнейший сбор информации включает в себя получение техническим писателем консультаций, возможную подготовку черновых версий и их обсуждение с консультантами и т. п.
Сбор информации о программном средстве продолжается вплоть до завершения разработки комплекта технической документации.
Составление структуры документации. Структура документации отражает результаты первичного сбора информации о программном средстве. Составленная структура обсуждается с консультантами, корректируется и служит основой для дальнейшей работы. Написание текста. Текст технической документации пишется с соблюдением принятых стандартов и требований качества, оговоренных ранее, при постановке задачи.
Изготовление иллюстраций. Иллюстрации подготавливаются в соответствии со всеми требованиями стандартов и технической культуры. Возможна подготовка как цветных, так и черно-белых иллюстраций. При необходимости изображения рабочих окон программного средства снабжаются вспомогательными элементами (указательными стрелками, линиями разреза и т. п.), облегчающими понимание иллюстрации.
28
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
Создание аппарата документа. Аппаратом документа (в широком смысле) является ряд элементов текста и ряд его разделов, облегчающих пользование текстом и его восприятие. Аппарат технической документации состоит из следующих основных элементов:
•	перекрестные ссылки;
•	оглавление;
•	список иллюстраций;
•	список таблиц;
•	указатель;
•	глоссарий.
Системы контекстной справки снабжаются аппаратом, который предусмотрен избранным форматом справки. Например, справка в формате HTML Help имеет оглавление, указатель, гиперссылки из одного раздела в другой, ссылки типа «См. также» и т.п.
Подготовка публикации может включать в себя следующие виды обработки готового документа (рис.1.1).
Сборка документа или комплекта документации. Сборка документации осуществляется в тех случаях, когда несколько технических писателей работают над отдельными частями документации. В этих случаях по завершении работы над частями выполняются следующие действия:
•	соединение частей документации воедино;
•	формирование единого аппарата документации;
•	выявление терминологических расхождений и их устранение.
Литературное редактирование. Литературное редактирование выполняется в тех случаях, когда к стилю документации предъявляются достаточно высокие требования. Литературное редактирование включает в себя следующие аспекты:
•	устранение стилистических недочетов;
•	приведение текста в соответствие со специальными требованиями заказчика;
•	устранение случайных терминологических недочетов (нарушения единства терминологии, неправильное употребление терминов и Т.Д.).
Верстка. В большинстве случаев той минимальной верстки, которую осуществляет технический писатель на стадии написания текста
1.1.	ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
29
Рис. 1.1. Обработка документа при подготовке пуликации
30
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
недостаточно. Для подготовки печатной публикации осуществляется верстка текста. Верстка текста выполняется различными путями.
Электронная публикация также нуждается в верстке. Подготовка электронной публикации подчиняется своим законам: учитывается не печатный, а экранный вид документа, используются дополнительные возможности электронных форматов (интерактивные оглавления и перекрестные ссылки, система закладок).
Один и тот же документ или комплект документов может быть сверстан для бумажной публикации и подготовлен в качестве электронной публикации.
Оформление по ГОСТ или другому стандарту. В случае если к оформлению документации предъявляются специализированные требования какого-либо стандарта (например, ГОСТ), выполняется определенная работа по переоформлению готовых документов. Переоформление фактически выполняется в рамках процесса верстки. Стандартное оформление документации облегчается за счет заготовленных заранее шаблонов и заготовленных образцов.
Эту работу, как и верстку в целом, теоретически может выполнить сам технический писатель. Однако обычно работу поручают профессиональному верстальщику, хорошо знакомому с используемым стандартом. Стандарты документирования ПС приведены в разделе 2.1..
Корректорская правка. Корректорская правка выполняется, если необходимо приблизить уровень подготовки технической документации к уровню профессиональных книжных изданий. Корректорская правка осуществляется профессиональными корректорами. Часто возникает необходимость оперативного выполнения корректорской правки большого объема текста. В этом случае правка выполняется большим количеством корректоров и координируется редактором.
Производство технической документации следует за разработкой технической документации, ее тестированием и подготовкой публикации и непосредственно предшествует распространению. Производство - процесс преобразования материалов из рабочего формата, в котором осуществляется разработка документации и подготовка публикации, в формат, пригодный для распространения. Производство может включать следующие процессы.
• Изготовление электронного документа в формате PDF. Электронный документ первоначально создается с использованием одного из упомянутых выше инструментов.
1.1. ОБ ОСНОВНЫХ КОМПЕТЕНЦИЯХ
31
• Изготовление печатной публикации. При изготовлении печатной публикации предпринимаются следующие последовательные действия:
—	преобразование подготовленного ранее макета в формат PDF;
—	размещение заказа в типографии;
—	передача материалов в типографию;
—	получение тиража.
При подготовке печатной документации обычно имеет большое значение типографское качество продукции и соблюдение сроков поставки. Поэтому, если есть такая возможность, прибегают к услугам типографий, известных как качеством, так и оперативностью работы. Компании, специализирующиеся в области технических коммуникаций, обычно сотрудничают с несколькими типографиями на постоянной основе. Этот подход имеет еще и то преимущество, что нет необходимости каждый раз формулировать во всех подробностях требования к конечной продукции: исполнитель уже неоднократно сталкивался с подобной работой и знаком с полиграфическими требованиями к технической документации.
Разные типографии принимают исходные материалы в разной форме. Некоторые из них готовы работать с макетом в рабочем формате. Другие предъявляют более жесткие требования. Оптимальным является порядок, при котором в типографию передается файл или файлы в формате PDF, в которых содержится готовый оригинал-макет будущей публикации. Типография берет на себя изготовление пленок, печать и переплетные работы.
В случае если необходима печать нескольких экземпляров, к услугам типографии не прибегают. Печать выполняется на лазерном принтере. Брошюровку осуществляют своими силами или прибегают к услугам переплетных мастерских.
Компиляция справочной системы. Работа по подготовке системы контекстной справки организуется в виде цикла, который включает постоянную работу по подготовке и обновлению текста и периодическую компиляцию итоговых файлов (в формате WinHelp, HTML Help и т.п.). Какие бы средства не использовались для подготовки текста справки: специализированные инструменты, произвольные HTML-или RTF-редакторы, технология единого источника на основе DocBook
32
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
или какие-то иные технологии, - производство итоговых файлов выполняется посредством запуска стандартного компилятора справки выбранного формата.
1.2.	О работе технического писателя
Технического писателя в настоящее время еще называют интеллектуальным кентавром, лучшим гуманитарием среди технарей и лучшим технарем среди гуманитариев [17].
После набора строки * технический писатель» в поисковой системе становится ясно, что технический писатель - явление новое. Однако это совсем не так. В странах, которые раньше было принято называть капиталистическими, такая профессия появилась примерно в 50-х (Великобритания, США) - 60-х (Австралия) годах. Писателей нанимали крупные производители бытовой электроники, и их основной задачей была разработка руководств и инструкций к сложным механическим приборам [11].
Основная масса специализированной библиографии по документированию прослеживается примерно с того же времени. При этом литература по коммуникации в широком смысле этого слова начала появляться уже в начале XX столетия. Примером тому может служить книга Вильяма Странка младшего «The Elements of Style», впервые изданная еще в 1918 году и читаемая по сей день специалистами во многих странах [11].
Наиболее интересные и востребованные зарубежные книги по документированию были написаны между 1970 и 1995 годами. С одной стороны, к тому времени уже окончательно сформировалось понятие о технической коммуникации, развилось профессиональное сообщество, и были сформулированы многие проблемы, а с другой - началось активное использование компьютерной техники, расширившее границы профессии, потребовавшее пересмотра и дополнения стандартов, методов и принципов документирования.
Сегодня технический писатель в большом мире признан и самостоятельной специальностью, и самостоятельной профессией. Одно из доказательств тому - принятая в 1998 году резолюция Совета Европы от 17 декабря 1998 года, в которой говорится о необходимости этой профессии «доя обеспечения потребителям доступа к адекватной
1.2. О РАБОТЕ ТЕХНИЧЕСКОГО ПИСАТЕЛЯ
33
эксплуатационной документации, гарантирующей корректное и полноценное использование продукта». В начале 2012 года в России Ассоциацией предприятий компьютерных и информационных технологий (http://www.apkit.ru), наконец-то, утвержден профессиональный стандарт «Технический писатель» в области информационных технологий. В ближайшее время он будет опубликован в сети Интернет.
В сферу деятельности технических писателей также входит подбор иллюстраций, графиков и диаграмм, подготовка видео материалов, мультимедийных продуктов и веб-сайтов. Существует точка зрения, что системные сообщения и отчеты об ошибках программ - также область коммуникации, требующая понимания пользователя, поэтому технические писатели должны участвовать и в их разработке. Тем не менее, к этой работе писатели привлекаются крайне редко на этапе редактирования, или не привлекаются вовсе. В зарубежных источниках говорится, что иногда технических писателей приглашают в качестве консультантов на стадии разработки интерфейса, полагаясь на их квалификацию в методах подачи информации.
Термин «технический писатель» представляет собой далекую от изящества кальку, буквальный перевод английского названия профессии «technical writer» или «Technical communicator». Приведем название профессии в других европейских языках:
•	Redacteur Technique (французский);
•	Technischer Redakteur (немецкий);
•	Redactor T6cnico, Autor Тёсшсо(испанский);
•	Redattore Tecnico (итальянский).
Должность, которую занимает технический писатель, - разработчик технической документации. В официальных классификаторах специальностей и должностей ничего отдаленно похожего на «технический писатель» не наблюдается.
Что такое техническая документация, на бытовом уровне, скорее всего, понятно многим. При покупке программного продукта в магазине (домашней бухгалтерии или компьютерной игры) вместе с дисками и рекламными материалами с этим продуктом поставляется и книга, озаглавленная «Руководство пользователя». В ней сказано, как установить программу на компьютер, как запустить ее, и, наконец, как с ней работать.
Эту книгу и составляет технический писатель. Он пишет: ^Данная программа предназначена для решения таких-то и таких-то задач.
34
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
Для того чтобы установить программу на компьютер, сделайте то-то и то-то. Для того чтобы запустить программу, щелкните мытью по такому-то значку. Для того чтобы сформировать вату налоговую декларацию за протедтий год, выберите в меню ’’Налоговая декларация” и т.д.».
Каждую задачу, которую решает пользователь с помощью программы, технический писатель должен изложить очень подробно, по шагам, ничего не пропуская. Всякому пользователю после прочтения такой документации должно быть понятно, что и как можно сделать. Очевидно, этот идеал достигается не всегда, не всегда в полной мере достижим, но добросовестный технический писатель к нему стремится.
Написать хорошее руководство пользователя можно только в том случае, если знать программу в мельчайших деталях. Но этого не достаточно. Нужно еще уметь посмотреть на программу с точки зрения пользователя, влезть в его шкуру, заговорить с ним на его языке, понять его задачи, постараться предугадать, что ему будет непонятно. Можно сказать, что главный герой руководства как раз пользователь, а не программа.
С программами для корпоративного пользования работают профессионалы в разных предметных областях: финансисты, инженеры, геологи, врачи, авиадиспетчеры, криминалисты и прочие. Тогда техническому писателю приходится осваивать соответствующую предметную область. Конечно, он не становится в ней настоящим специалистом, но узнает о ней очень много.
Технический писатель работает не только в тех компаниях, которые выпускают и продают < коробочные» программы. Многие компании разрабатывают автоматизированные системы по заказу других организаций, коммерческих, общественных или государственных. Принципиальным отличием автоматизированной системы от программы является то, что она функционирует в некоторой конкретной организации и служит для автоматизации ее деятельности. Иначе говоря, программа - это только часть автоматизированной системы.
Допустим, некое министерство N-ского уезда хочет, чтобы все подчиненные ему заборы были занесены в единый государственный реестр. Для ведения этого реестра нужна особая автоматизированная система. Поскольку раньше никому в голову ничего подобного не приходило, программу, предназначенную для решения такой задачи, на
1.2. О РАБОТЕ ТЕХНИЧЕСКОГО ПИСАТЕЛЯ
35
рынке не найти. Приходится заказывать, чтобы ее разработали с нуля (или не совсем с нуля и даже совсем не с нуля, но это уже детали), а потом еще внедрили в министерстве, т.е. установили на компьютерах у чиновников и научили их ею пользоваться.
Министерство объявляет конкурс, находит компанию-исполнителя и заказывает ей разработку Единой государственной автоматизированной информационной системы. Разработка заказной автоматизированной системы, особенно по государственному контракту, сопровождается выпуском большого объема технической документации. Конечно, необходима разноплановая эксплуатационная документация. Она адресована:
•	ИТ-специалистам, которые будут обслуживать систему в министерстве, обеспечивать ее бесперебойное функционирование;
•	министерским начальникам (среднего уровня), которым предстоит наладить процесс в целом, организовать учет заборов с помощью системы;
•	самим чиновникам, которые будут заняты учетом заборов.
Технический писатель должен вжиться в роль каждого из этих адресатов и написать документ, отвечающий задачам каждого из них. Столь объемная и сложная работа выполняется коллективами технических писателей. Кроме того, ее можно автоматизировать, в общем, инженерный подход избавляет от необходимости длительного творческого поиска.
Документирование автоматизированной системы не сводится к созданию эксплуатационной документации. Много разных документов выпускается до того, как программистами будет написана хоть строчка кода (а может быть, они вообще ничего писать не будут, а построят систему из готовых программ, скомплектовав и соединив их нужным образом). Разрабатывается концепция системы и техническое задание на нее. Технический писатель занимается не только документированием тиражируемых или заказных разработок. В каждой крупной и во многих средних организациях есть подразделения, которые отвечают за информационные технологии. Они могут называться по-разному, но будем для определенности использовать термин ИТ-департамент. В настоящее время в каждом офисе работа секретарей, клерков и прочих эффективных менеджеров в большей или меньшей степени автоматизирована. Документооборот, планирование, маркетинг, производство, продажи, логистика, управление персоналом, учет - все, даже про
36
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
стая переписка, теперь происходит в электронной корпоративной информационной среде. Однако кто-то должен закупать и настраивать компьютеры, приобретать и устанавливать на них программы, заказывать или самостоятельно разрабатывать автоматизированные системы. Еще нужно обучать сотрудников, решать возникающие у них проблемы с техникой, заботиться о сохранности конфиденциальных данных и т.д. Все это забота ИТ-департамента. В ИТ-департаменте у технического писателя тоже может быть много дел. Как минимум, необходимо документировать разработки, которые ИТ-департамент ведет собственными силами. К тому же вся ИТ-инфраструктура в целом должна быть документирована, иначе ее будет очень сложно обслуживать, развивать, адаптировать к потребностям бизнеса.
В зависимости от особенностей организационной структуры компании технический писатель может быть включен в профильное структурное подразделение либо непосредственно в команду разработчиков, занятых каким-то проектом или продуктом. Отдел документирования (как бы его ни называли в конкретной фирме) обычно не велик. Некоторые компании комплектуют отдел документирования не только техническими писателями, но и литературным редактором, корректором, верстальщиком. В компаниях с достаточно большим количеством уровней иерархии сам отдел может относиться к более крупному структурному подразделению, осуществляющему или разработку, или обеспечение качества («Quality Assurance», QA).
До самого последнего времени были распространены объединенные отделы документирования и тестирования, но эта практика постепенно изживает себя. Руководителем отдела документирования, как правило, назначают наиболее квалифицированного технического писателя. В разных компаниях ему могут присваивать разные функции, но в любом случае потребуют обеспечить соблюдение сроков подготовки технической документации и достаточный уровень ее качества. Даже при умелом управлении отдел документирования, как всякий общий ресурс, постоянно перегружен.
Поскольку еще не родился ребенок, который мечтал бы стать техническим писателем, ни один вуз сегодня не предлагает абитуриентам получить подобную специальность. По крайней мере, в России дело обстоит именно так, хотя за границей дипломированный «technical writer» вовсе не редкость. В армии офицер получает сначала должность, а после звание. Примерно то же самое происходит с техниче
1.2. О РАБОТЕ ТЕХНИЧЕСКОГО ПИСАТЕЛЯ
37
скими писателями. Хороший технический писатель может выйти из программиста, математика, филолога, педагога, географа, военного. Только одно обстоятельство портит картину: тот, кто никогда не написал самостоятельно ни одной программы, не сможет писать документацию, адресованную программисту. Это особая разновидность документации, которая обычно касается либо средств разработки (языки программирования, компиляторы, отладчики), либо технических интерфейсов для интеграции между программами. Правда, такие задачи возникают далеко не во всех компаниях.
Попробуем выделить несколько ключевых способностей, которыми технический писатель должен обладать обязательно, без них он профессионально непригоден.
Во-первых, он должен уметь составлять хороший доходчивый технический текст, излагать материал последовательно, грамотно, подробно; строго, но без лишнего наукообразия и канцеляризма, причем не сбиваться, придерживаться выбранного стиля на протяжении всего документа, возможно, довольно длинного. Кажется, эта способность сродни музыкальному слуху, или она есть, или ее нет.
Во-вторых, он должен уметь систематизировать и переосмыслять услышанное. Технический писатель - не секретарь-стенографист при программисте, его задача состоит не в буквальном переложении на бумагу сведений, сообщенных разработчиками. Он обязан даже не перевести эти сведения на язык своего читателя, а, пользуясь ими, написать какой-то совершенно другой, иначе структурированный, иначе развернутый текст, адекватный читательским потребностям. Кто-то наделен таким умением от природы, кто-то его может в себе выработать.
В-третьих, он должен иметь задатки следователя и биолога одновременно. Ведь какую-то часть нужных для написания документации сведений он получает у разработчиков путем опроса, а какую-то добывает, самостоятельно работая с программой. Впрочем, качественная техническая документация предшествующих стадий жизненного цикла (ЖЦ) могут значительно снизить объем этой работы.
В общем, технический писатель — это человек с очень хорошо развитыми коммуникативными навыками с одной стороны и с чрезвычайно систематичным тотально все упорядочивающим на свой лад мышлением с другой.
38
1. О ДОКУМЕНТИРОВАНИИ В ИТ-ПОДРАЗДЕЛЕНИИ
Все остальное сводится к некоторым системным представлением и знакомству с определенными стандартами и инструментами, это сумма знаний, которая набирается постепенно. Тем не менее, перечислим основные знания технического писателя [16]:
•	представление о системной и программной инженерии как о суперсистеме для документирования;
•	системное видение документирования как инженерной дисциплины, понимание процессов документирования и их взаимосвязей с другими процессами в разных ситуациях;
•	международные стандарты, касающиеся жизненных циклов программ и систем и их документирования (ISO, IEEE);
•	отечественные стандарты, касающиеся программ и систем и их документирования (ГОСТ, ГОСТ Р);
•	отечественные стандарты на конструкторскую и технологическую документацию (ЕСКД, ЕСТД);
•	методологии и практики ведущих компаний (RUP, MSF);
•	инструментальные средства для разработки электронной справки (Microsoft HTML Help Workshop, HelpManual, RoboHELP);
•	технологии и средства для автоматизации документирования, в том числе для работы с единым источником (AuthorlT, DocBook/XML, DITA, SiberSafe);
•	текстовые процессоры и специализированные пакеты для подготовки технических публикаций (Adobe FrameMaker, Microsoft Word, OpenOffice);
•	языки разметки (HTML, XML и его приложения) и средства для работы с ними;
•	языки программирования, позволяющие автоматизировать разработку технической документации (VBA, XSLT);
•	понимание основ современных информационных технологий, основных идей, таких, как реляционные (и нереляционные) базы данных,
•	локальные и глобальные сети, клиент-серверные технологии, объектно-ориентированное программирование и т.п.
•	методологии и языки моделирования (IDEF0, DFD-диаграммы, ER-диаграммы, UML) на уровне, который позволяет читать модели;
•	владение лингвистическим понятийным аппаратом и терминологией на уровне, который позволяет вести обсуждение текста при
1.2. О РАБОТЕ ТЕХНИЧЕСКОГО ПИСАТЕЛЯ
39
формулировании требований к его стилю, при его критике и редактировании;
• умение пользоваться нормативно-справочной литературой по естественному языку, на котором технический писатель пишет.
Специалист, который обладает всеми перечисленными способностями и знаниями в полной мере, скорее всего, давно не работает техническим писателем. Это какой-то невиданный технологический гуру. Но у профессионального технического писателя все перечисленное должно находиться в поле зрения, входить в его профессиональный кругозор. Тогда его квалификация, зарплата и административная позиция будут с большей или меньшей скоростью расти.
Спрос на технических писателей нынче высок, повышается и в обозримое время повышаться не прекратит. Менеджеры некоторых компаний не представляют себе, как должно быть организовано документирование, и кому следовало бы доверить работу по его налаживанию, иными словами, они не готовы объявить об имеющейся у них вакансии. Кроме того, специалистов по документированию высокого уровня объективно не хватает.
Согласно отчету STC от 2003 года, доход европейского технического писателя может достигать 90 000 евро в год. В то же время по данным сайтов с вакансиями, максимальный годовой доход его коллеги, квалифицированного технического писателя из Москвы или Санкт-Петербурга, пишущего на английском языке и работающего в крупной компании или в филиале иностранной фирмы в несколько раз меньше (около 20 000 - 25 000 долларов в год). Зарплата технического писателя в других крупных российских городах - порядка 10 000 долларов в год.
2.	Цели и принципы документирования программных средств
Одна из важнейших задач документирования [3] состоит в том, чтобы увязать четкими экономическими категориями взаимодействие разных специалистов в типовой производственной цепочке: заказчик -разработчик - изготовитель - пользователь документации. Для этого объект потребления - программный продукт, его документация и все процессы взаимодействия в цепочке должны быть связаны системой экономических и технических характеристик, в той или иной степени использующих основные экономические показатели - реальные затраты ресурсов: финансов, труда и времени специалистов на конечный программный продукт и документы. Сложность документирования, количество и полнота содержания комплекса документов в первую очередь зависят от масштаба — размера проекта ПС, что целесообразно оценивать в начале его ЖЦ.
Для решения этой задачи необходимо детально учитывать требуемые ресурсы современных процессов создания, документирования и использования программ различных классов и назначения: встроенных, коммерческих, административных, учебных, уникальных.
40
2.1. СТАНДАРТЫ ДОКУМЕНТИРОВАНИЯ ПС
41
2.1.	Стандарты документирования программных средств
Как можно раньше вступайте на проторенную стезю. Не изменяйте своим привычкам.
Накапливайте идиомы.
Стандартизируйте.
Единственная разница между Шекспиром и вами состоит не в объеме словаря, а в количестве идиом.
(Алан Дж.Перлис)
Когда программист-разработчик получает в той или иной форме задание для программирования, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы:
•	что должно быть сделано, кроме программы,
•	что и как должно быть оформлено в виде документации,
•	что передавать пользователям, а что - службе сопровождения,
•	как управлять всем этим процессом?
Кроме упомянутых вопросов есть и другие, например, что должно входить в само задание для программирования?
На эти и массу других вопросов когда-то отвечали государственные стандарты на программную документацию - комплекс стандартов 19-й серии ГОСТ ЕСПД (Единой системы программной документации), разработанный в конце 70-х годов XX века. Но уже тогда у программистов была масса претензий к этим стандартам. Что-то требовалось дублировать в документации много раз, а многое не было предусмотрено, как, например, отражение специфики документирования программ, работающих с интегрированной базой данных.
Прошло много лет, программирование происходит в среде совершенно новых технологий, многие программисты, работая в стиле drag-and-drop (например, как в 1С или в средах визуального программирования), могут годами не видеть тексты своих программ. Это не значит, что исчезла необходимость в документировании полученных таким образом программных продуктов. Более того, вопросы о наличии хоть
42
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
какой-то системы, регламентирующей эту сторону создания программного средства (ПС), до сих пор актуальны. Многих технических писателей интересует вопрос, имеются ли обязательные для применения стандарты (этот вопрос особенно остро стоит, когда разработка выполняется по заказу государственной организации или предприятия). Интересуются и тем, где можно купить имеющиеся стандарты.
Попробуем разобраться в некоторых из этих вопросов и дать свое представление о том, как целесообразно использовать существующие стандарты и развивать систему стандартов. Будем говорить только о стандартах на документирование ПС, не касаясь стандартов на разработку автоматизированных систем в целом или более специфических стандартов, например, направленных на стандартизацию языков про-грам мирования.
Основу отечественной нормативной базы в области документирования ПС составляет комплекс стандартов ЕСПД. Основная и большая часть комплекса была разработана в 70-е и 80-е годы XX века. Сейчас этот комплекс представляет собой систему межгосударственных стандартов стран СНГ (ГОСТ), действующих на территории Российской Федерации на основе межгосударственного соглашения по стандартизации.
Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС. Они связаны, по большей части, с документированием функциональных характеристик ПС.
Следует отметить, что стандарты ЕСПД носят рекомендательный характер. Впрочем, это относится и ко всем другим стандартам в области ПС. Дело в том, что в соответствии с Законом РФ «О стандартизации» эти стандарты становятся обязательными на контрактной основе - то есть при ссылке на них в договоре на разработку (поставку) ПС. Говоря о состоянии ЕСПД в целом, можно констатировать, что большая часть стандартов ЕСПД морально устарела.
К числу основных недостатков ЕСПД можно отнести [8]:
•	ориентацию на единственную, «каскадную» модель жизненного цикла (ЖЦ) ПС;
•	отсутствие четких рекомендаций по документированию характеристик качества ПС;
•	отсутствие системной увязки с другими действующими отечественными системами стандартов по ЖЦ и документированию продукции в целом, например, СРПП и ЕСКД;
2,1, СТАНДАРТЫ ДОКУМЕНТИРОВАНИЯ ПС
43
•	нечетко выраженный подход к документированию ПС как товарной продукции;
•	отсутствие рекомендаций по самодокументированию ПС, например, в виде экранных меню и средств оперативной помощи пользователю («хелпов»);
•	отсутствие рекомендаций по составу, содержанию и оформлению перспективных документов на ПС, согласованных с рекомендациями международных и региональных стандартов.
Итак, ЕСПД нуждается в полном пересмотре на основе стандарта ИСО/МЭК 12207-95 на процессы жизненного цикла ПС.
Тем не менее, до пересмотра всего комплекса, многие стандарты могут с пользой применяться в практике документирования ПС. Эта позиция основана на следующем:
•	стандарты ЕСПД вносят элемент упорядочения в процесс документирования ПС;
•	предусмотренный стандартами ЕСПД состав программных документов вовсе не такой «жесткий», как некоторым кажется: стандарты позволяют вносить в комплект документации на ПС дополнительные виды программных документов (ПД), необходимых в конкретных проектах, и исключать многие ПД;
•	стандарты ЕСПД позволяют вдобавок мобильно изменять структуры и содержание установленных видов ПД исходя из требований заказчика и пользователя.
При этом стиль применения стандартов может соответствовать современному общему стилю адаптации стандартов к специфике проекта: заказчик и руководитель проекта выбирают уместное в проекте подмножество стандартов и ПД, дополняют выбранные ПД нужными разделами и исключают ненужные, привязывают создание этих документов к той схеме ЖЦ, которая используется в проекте.
Надо сказать, что наряду с комплексом ЕСПД официальная нормативная база РФ в области документирования ПС и в смежных областях включает ряд перспективных стандартов (отечественного, межгосударственного и международного уровней), о составе и содержании которых будет сказано ниже.
Из всех 28 стандартов ЕСПД остановимся только на тех, которые могут чаще использоваться на практике. Выделим также еще один,
44
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
существенно более «свежий», чем остальные, отличающийся совместимостью с современными международными стандартами.
В первую очередь укажем стандарт, который можно использовать при формировании заданий на программирование.
ГОСТ 19.201-78 ЕСПД. Техническое задание. Требование к содержанию и оформлению. Напомним, что техническое задание (ТЗ) содержит совокупность требований к ПС и может использоваться как критерий проверки и приемки разработанной программы. Поэтому достаточно полно составленное (с учетом возможности внесения дополнительных разделов) и принятое заказчиком и разработчиком, ТЗ является одним из основополагающих документов проекта ПС. О содержании этого документа и примеры составленных ТЗ см. в разделе 2.8.
Следующий стандарт ориентирован на документирование результирующего продукта разработки: ГОСТ 19.402-78 ЕСПД. Описание программы.
Здесь следует отметить два очень важных момента.
1	. Несмотря на возможность применения не всех, а только отдельных стандартов комплекса, использованная в них терминология, способы обозначения и другие детали могут потребовать опоры на такие общие стандарты, как ГОСТ 19.101-77 ЕСПД. Виды программ и программных документов, и другие.
2	. Состав документа «Описание программы» в своей содержательной части может дополняться разделами и пунктами, почерпнутыми из стандартов для других описательных документов и руководств: ГОСТ 19.404-79 ЕСПД. Пояснительная записка, ГОСТ 19.502-78 ЕСПД. Описание применения, ГОСТ 19.503-79 ЕСПД. Руководство системного программиста, ГОСТ 19.504-79 ЕСПД. Руководство программиста, ГОСТ 19.505-79 ЕСПД. Руководство оператора.
Есть также группа стандартов, определяющая требования к фиксации всего набора программ и ПД, которые оформляются для передачи ПС. Они порождают лаконичные документы учетного характера и могут быть полезны для упорядочения всего хозяйства программ и ПД (ведь очень часто требуется просто навести элементарный порядок!). Есть и стандарты, определяющие правила ведения документов в «хозяйстве» ПС.
Надо также выделить ГОСТ 19.301-79 ЕСПД. Программа и методика испытаний, который (в адаптированном виде) может ис
2.1. СТАНДАРТЫ ДОКУМЕНТИРОВАНИЯ ПС
45
пользоваться для разработки документов планирования и проведения испытательных работ по оценке готовности и качества ПС.
Наконец, выделим последний по году принятия стандарт. Это ГОСТ 19.701-90 ЕСПД. Схемы алгоритмов, программ, данных и систем. Обозначения условные графические и правила выполнения. Он устанавливает правила выполнения схем, используемых для отображения различных видов задач обработки данных и средств их решения, и полностью соответствует стандарту ИСО 5807:1985.
Наряду с ЕСПД на межгосударственном уровне действуют еще два стандарта, также относящихся к документированию ПС и принятых не так давнопо сравнению с большей частью ГОСТ ЕСПД.
ГОСТ 19781-90 Обеспечение систем обработки информации программное. Термины и определения. Разработан взамен ГОСТ 19781-83 и ГОСТ 19.004-80 и устанавливает термины и определения понятий в области программного обеспечения (ПО) систем обработки данных (СОД), применяемые во всех видах документации и литературы, входящих в сферу работ по стандартизации или использующих результаты этих работ.
ГОСТ 28388-89 Системы обработки информации. Документы на магнитных носителях данных. Порядок выполнения и обращения. Распространяется не только на программные, но и на конструкторские, технологические и другие проектные документы, выполняемые на магнитных носителях.
В РФ действует ряд стандартов в части документирования ПС, разработанных на основе прямого применения международных стандартов ИСО. Это самые «свежие» по времени принятия стандарты. Некоторые из них впрямую адресованы руководителям проекта или директорам информационных служб. Вместе с тем они неоправданно мало известны в среде профессионалов. Вот их представление.
ГОСТ Р ИСО/МЭК 9294-93 Информационная технология. Руководство по управлению документированием программного обеспечения. Стандарт полностью соответствует международному стандарту ИСО/МЭК ТО 9294:1990 и устанавливает рекомендации по эффективному управлению документированием ПС для руководителей, отвечающих за их создание. Целью стандарта является оказание помощи в определении стратегии документирования ПС; выборе стандартов по документированию; выборе процедур докумен
46
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
тирования; определении необходимых ресурсов; составлении планов документирования.
ГОСТ Р ИСО/МЭК 9126-03 Информационная технология. Оценка программной продукции. Характеристики качества и руководства по их применению. Стандарт полностью соответствует международному стандарту ИСО/МЭК 9126:1991. В его контексте под характеристикой качества понимается «набор свойств (атрибутов) программной продукции, по которым ее качество описывается и оценивается». Стандарт определяет шесть комплексных характеристик, которые с минимальным дублированием описывают качество ПС (ПО, программной продукции): функциональные возможности; надежность; практичность; эффективность; сопровождаемость; мобильность. Эти характеристики образуют основу для дальнейшего уточнения и описания качества ПС.
ГОСТ Р ИСО 9127-94 Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов. Стандарт полностью соответствует международному стандарту ИСО 9127:1989. В контексте настоящего стандарта под потребительским программным пакетом (ПП) понимается «программная продукция, спроектированная и продаваемая для выполнения определенных функций; программа и соответствующая ей документация, упакованные для продажи как единое целое». Под документацией пользователя понимается документация, которая обеспечивает конечного пользователя информацией по установке и эксплуатации ПП. Под информацией на упаковке понимают информацию, воспроизводимую на внешней упаковке ПП. Ее целью является предоставление потенциальным покупателям первичных сведений о ПП.
ГОСТ Р ИСО/МЭК 8631-94 Информационная технология. Программные конструктивы и условные обозначения для их представления. Описывает представление процедурных алгоритмов.
Как уже говорилось, пока нет лучшего, можно извлекать пользу и из тех стандартов ЕСПД, которые приняты еще 20-30 лет назад. Но всем ясно, что ориентироваться надо на современные стандарты. Практики используют еще один путь: сами переводят с английского и используют в своих проектах современные стандарты на организацию ЖЦ ПС и их документирование. Но этот путь страдает как минимум тем недостатком, что разные переводы и адаптации стандартов,
2.1. СТАНДАРТЫ ДОКУМЕНТИРОВАНИЯ ПС
47
сделанные разными разработчиками и заказчиками, будут отличаться массой деталей. Эти отличия неизбежно касаются не только наименований, но и их содержательных определений, вводимых и используемых в стандартах. Таким образом, на этом пути неизбежно постоянное возникновение путаницы, а это прямо противоположно целям не только стандартов, но и любых грамотных методических документов. Так, в разделе 2.10. приведен один из вариантов перевода стандарта для процедуры тестирования ПС, выполненный автором данного пособия.
ГОСТ Р ИСО/МЭК 12119:2000. Информационная технология. Пакеты программных средств. Требования к качеству и испытания. В этом стандарте установлены требования к качеству пакетов программ и инструкции по их испытаниям на соответствие заданным требованиям. Понятие «пакет программных средств» фактически отождествляется с более общим понятием «программный продукт», рассматриваемым как совокупность программ, процедур и правил, поставляемых нескольким пользователям для общего применения или функционирования. Каждый пакет программ должен иметь описание продукта и пользовательскую документацию. Стандарт не связан с процессом производства пакетов программ (включая соответствующие работы и промежуточные продукты, например технические задания). Область применения настоящего стандарта не охватывает систему качества поставщика.
Отметим, что возникла настоятельная потребность во введении в отечественные стандарты на документирование ПС тех норм, правил, требований и рекомендаций, которые установлены на международном уровне. Но при проведении этих работ нельзя ограничиваться прямым переводом отдельных международных стандартов. Нужно, чтобы новые стандарты правильно стыковались с имеющимис нормативными документами.
В настоящее время во ВНИИ стандартов подготовлены предложения по совершенствованию и развитию комплекса стандартов по документированию ПС.
48
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.2.	Технологическая и эксплуатационная документация на программное средство
2.2.1.	Технологическая документация
Технологическая документация - это именно то, что подразумевают под термином «документация» большинство программистов. При создании программы, одного лишь кода, как правило, недостаточно. Должен быть предоставлен некоторый текст, описывающий различные аспекты того, что именно делает код. Такая документация часто включается непосредственно в исходный код или предоставляется вместе с ним.
Например, из комментариев в приведенном ниже исходном коде может быть легко получена документация для программиста.
//Удалить вершину по координатам
int TGraph2::DeleteVert(int x,int y)
int n=VertExist(x,y); //Получить неокер вершины, если она существует if (п)	//Если вершина существует - удалить
<
Vert_temp=new TVert[NVert-1]; //Создать временный массив
for(int i=0;i<NVert;i++) //Перенести элементы старого массива <
if (i<n-l) Vert_tenip[i]=Vert [i] ; //Элементы до удаляемого if (i>n-l) Vert_tempDJ=Vert[i+l]; //Элементы после удаляемого
}
delete []Vert; //Удалить старый массив
Vert=Vert_temp; //Сохранить ссылку на новый массив
NVert—;	//Уменьшить кол-во элементов
>
DeletePointRebr(x.y); return 0;
Подобная документация имеет сильно выраженный технический характер и в основном используется для определения и описания API, структур данных и алгоритмов.
Часто при составлении технической документации используются автоматизированные средства - генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из спе
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
49
циальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.
Использование генераторов документации и документирующих комментариев многими программистами признается удобным средством, по различным причинам. В частности, при таком подходе документация является частью исходного кода, и одни и те же инструменты могут использоваться для одновременной сборки программы и документации к ней. Это также упрощает поддержку документации в актуальном состоянии. Более подробно о различных средствах документирования рассказано в главе 3.
Технологическая документация непосредственно и в наибольшей степени должна отображать процессы жизненного цикла прикладных программ и данных и регламентировать требования к этим документам.
Стандарты и нормативные документы, входящие в жизненный цикл ПС, должны выполнять следующие функции [3].
1.	Регламентировать структуру и состав этапов, работ и документов ЖЦ ПС.
2.	Обеспечивать их адаптацию к характеристикам объекта проектирования, внешней и операционной среды.
3.	Поддерживать и регламентировать процессы организации и планирования реализации ЖЦ конкретных ПС.
4.	Формализовать выполнение и документирование конкретных работ при проектировании, разработке и сопровождении ПС.
5.	Регламентировать процессы обеспечения качества, показатели качества ПС и его компонентов, методы и средства их достижения, реальные значения достигнутых показателей качества.
Для контроля возможных изменений целесообразно предусмотреть и согласовать с заказчиком специальный документ, регламентирующий правила применения и корректировки номенклатуры документов ЖЦ ПС, а также состава и содержания поддерживающей его документации.
По функциональному назначению технологическую документацию ПС целесообразно разделить на следующие группы исходных документов.
1.	Базовые документы, определяющие цели и методологию применения конкретной версии ЖЦ ПС.
50
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.	Ссылочные документы на руководства по организации подобных разработок, включая общесистемные стандарты и нормативные документы различных уровней.
3.	Стандарты и нормативные документы, непосредственно регламентирующие работы и документы жизненного цикла программ, планирование и технологию разработки документации, состав и описание инструментальных средств автоматизации разработки.
4.	Стандарты и нормативные документы, непосредственно используемые при разработке, испытаниях и сопровождении программ на различных этапах.
Технологические документы создаваемых прикладных ПС должны определять следующие параметры.
1.	Структуру и содержание исходных и отчетных документов по этапам разработки, испытаний и сопровождения ПС.
2.	Логическую структуру программных и информационных компонентов и базы данных проекта ПС.
3.	Спецификации на внутренние межмодульные интерфейсы компонентов прикладных ПС и на интерфейсы с внешней средой ПС.
4.	Язык и правила программирования, идентификации компонентов, комментирования текстов программ и описаний данных.
5.	Методы тестирования, испытаний и аттестации программных компонентов и ПС в целом.
6.	Оформление, форматы и обозначения отчетных и результирующих документов.
2.2.2.	Эксплуатационная документация
Эксплуатационная документация должна обеспечить отчуждаемость ПС от их первичных разработчиков и возможность освоения и эффективного применения ПС достаточно квалифицированными специалистами.
Состав этой документации формируется выборкой из технологических документов с учетом требований заказчиков или потенциальных пользователей ПС.
Эксплуатационные документы должны исключать возможность некорректного использования ПС за пределами условий эксплуатации,
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
51
при которых документами гарантируются определенные показатели качества функционирования ПС»
При формировании эксплуатационных документов прикладных ПС, кроме базовых стандартов жизненного цикла должны использоваться ряд национальных стандартов, ведомственных нормативных документов и фирменных руководств.
Документация разработки образует основу документации сопровождения, которая может являться частью документации продукции, если разработчик допускает изменение программ и данных пользователями.
Эксплуатационная документация включает в себя.
1.	Руководства администраторов и операторов, осуществляющих инсталляцию и непосредственное управление режимами решения функциональных задач, регламентированными в информационной системе.
2.	Руководства операторов пользователей, использующих ПС по прямому назначению.
3.	Документацию сопровождения ПС, включая руководство по сопровождению и модификации программ и информации баз данных.
4.	Справочные руководства по применению программных средств.
5.	Учебные руководства по освоению программных средств и информационных систем.
Пользовательская эксплуатационная документация может поставляться на традиционных бумажных или электронных носителях.
Коммерческие пакеты прикладных ПС целесообразно снабжать бумажными документами в соответствии со стандартом ISO 9127.
Кроме представленных классов формализованных документов в ряде случаев целесообразно подготавливать исследовательскую документацию. Она имеет экспериментальный характер, зависящий от возможных целей исследования.
Основная ее задача - фиксирование и обобщение характеристик объектов и процессов всего ЖЦ ПС и информационной системы.
Этой документацией пользуются в основном руководители, разработчики и исследователи реализации проектов при анализе технологий, планировании новых разработок ПС или их переносе на иные платформы.
52
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Из-за разнообразия исследовательских задач этот тип документации практически всегда имеет оригинальный состав и содержание и пока не стандартизируется.
Состав комплекта эксплуатационной документации на программный продукт зависит от архитектуры последнего, назначения его компонентов и особенностей пользовательской аудитории.
Наиболее распространенные типы эксплуатационных документов приведены в табл. 2.1. В следующих разделах подробно рассмотрим каждый из документов.
2.2.3.	Описание программы и применения
Задачей данного описания является формирование верного и полного представления о возможностях и условиях применения программы. Для написания документа используются ГОСТ 19.402-78 и 19.502-78.
Этот документ составляется, в основном, для менеджеров, которые только принимают решение о приобретении программы и определяют порядок ее применения. Этим людям необходимо увидеть все возможности программы и оценить требуемые для работы этой программы ресурсы.
В описании программы и описании применения должно быть отмечено:
•	для чего предназначена программа, какие задачи она позволяет решать;
•	какие ресурсы необходимы для выполнения программы;
•	какие данные программа принимает на вход;
•	что программа выдает в качестве выходных данных.
Описание программы предполагает большую, а описание применения меньшую подробность изложения.
При составлении обоих документов следует избегать лишних подробностей. Следует писать о том, какие задачи позволяет решить программа, а не о том, каким образом это сделать. Следует перечислить, что необходимо для ее выполнения, а не объяснять, как она устроена.
Структура описания программы, согласно ГОСТ 19.402-78 состоит из разделов:
•	общие сведения;
•	функциональное назначение;
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
53
Таблица 2.1. Эксплуатационная документация на программный продукт
Документ	Аудитория	Примерное содержание
Описание программы	Лица, принимающие решения о приобретении, вводе в эксплуатацию и способах использования программы	Назначение и основные возможности программы, необходимые ей системные ресурсы, входные и выходные данные
Описание применения		
Описание языка	Пользователи языка (программисты, операторы, кодеры, верстальщики)	Основная идея языка, его синтаксис, элементы и конструкции, встроенные функции
Паспорт	Лица, ответственные за эксплуатацию программы	Краткие сведения о программе и условиях ее поставки
Руководство администратора	Ответственный пользователь	Управление учетными записями пользователей, назначение пользователям системы, обеспечивающий ее целевое применение прав доступа, ведение нормативно-справочной информации, загрузка и выгрузка данных
Руководство оператора	Операторы, работающие с системой, частью которой является программа	Порядок выполнении предусмотренных операций, сообщения программы и предписанные оператору способы реакции на них
Руководство пользователя	Пользователи программы, т.е. лица, применяющие ее для решения собственных прикладных задач	Назначение и возможности программы, пользователя, порядок решения типовых задач, описание функций программы
54
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Окончание таблицы 2.1
Руководство программиста	Программисты, сопровождающие программу или использующие ее в качестве платформы либо средства разработки при создании собственных программ	Архитектура программы или создаваемых на ее основе приложений, описание программных интерфейсов к ее объектам, протоколов обмена данными и т.п.
Руководство системного администратора (системного программиста)	Системные администраторы, осуществляющие установку программы и поддерживающие систему в рабочем состоянии	Установка программы, ее интеграция в систему, проверка правильности функционирования, устранение аварийных ситуаций
Спецификация	Лица, ответственные за эксплуатацию программы	Комплект поставки программы
Справочная система	Пользователи, операторы, администраторы, системные администраторы, программисты и др.	Материал всех имеющихся руководств и описаний, краткие описании элементов интерфейса пользователи программы
Формулир	Лица, ответственные за эксплуатацию программы	Краткие сведения о программе и условиях ее поставки, записи эксплуатационного о возникающих сбоих и прочих событиях такого рода
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
55
•	описание логической структуры;
•	используемые технические средства;
•	вызов и загрузка;
•	входные данные;
•	выходные данные.
Структура описания применения согласно ГОСТ 19.502-78 выглядит следующим образом:
•	назначение программы;
•	условия применения;
•	описание задачи;
•	входные и выходные данные.
2.2Л. Описание языка
Описание языка (которое осуществляется по ГОСТ 19.504-79) приводится с целью обеспечить пользователю возможность решать задачи, которые могут быть перед ним поставлены, на описываемом формальном языке.
К формальным языкам относятся всевозможные языки программирования, языки управления заданиями, языки описания экранных и печатных форм, языки описания структур данных, языки разметки и т.п. Они могут быть очень разными. Кроме очевидного свойства, состоящего в том, что все это искусственные языки с определенным набором элементов (слов) и строгими грамматическими правилами.
Программист, оператор, кодер, верстальщик (все пользователи языка) могут узнать о свойствах и возможностях языка только из описания. Программу или даже устройство можно в той или иной мере изучать методом проб и ошибок, но по отношению к языку такой метод совсем не работает. Правда, язык можно изучать, читая написанный на нем код. Однако, даже изучив сотню страниц, не будет уверенности в том, что произошло знакомство со всеми словами и конструкциями. Более того, нет никакой гарантии в правильности понимания всего прочитанного.
Таким образом, задача описания языка состоит в том, чтобы дать читателю исчерпывающее представление о формальном языке и обеспечить ему возможность применять язык в полном объеме.
В описании языка должны быть изложены следующие сведения [25].
56
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Назначение и сфера применения языка. Чем является текст, написанный на этом языке. Иначе говоря, что на этом языке пишут: программы, макросы, документы определенного назначения и т.п.
Основные синтаксические правила языка, т. е. типы элементов текста и допустимые способы их соединения друг с другом. Например, программа на алгоритмическом языке вроде Фортрана или Бейсика представляет собой последовательность операторов, a XML-документ - дерево вложенных друг в друга элементов.
Логика исполнения программы или обработки документа. В разных языках она, вообще говоря, разная. Например, операторы в программе на алгоритмическом языке обрабатываются последовательно сверху вниз (если эта последовательность не изменяется явно посредством всевозможных операторов перехода и ветвления или неявно механизмами вроде исключений). И совсем по-другому происходит применение XSLT-стиля к XML-документу или CSS-стиля к HTML-документу.
Конкретные элементы языка и связанные с ними синтаксические конструкции. В случае языка программирования это, как правило, операторы, в случае языка разметки всевозможные элементы или ключи.
Встроенные функциональные блоки, например, стандартные функции.
Кроме того, в описании языка могут быть приведены:
•	рекомендации по стилю программирования (кодирования);
•	типология ошибок, методы их выявления и поиска;
•	методы оптимизации по быстродействию, памяти и прочим параметрам;
•	перечень рекомендованных трансляторов, фреймворков или парсеров.
А также любые другие детали, знание которых помогает пользователю делать свою работу по возможности хорошо и быстро.
Пограничная тема - сообщения об ошибках, выводимые транслятором или парсером. С одной стороны, их описание необходимо программисту. С другой стороны, для одного языка (скажем, для JavaScript и XSLT) может существовать много разных обрабатывающих программ, и у каждой из них могут быть свои сообщения об одних и тех же ошибках. Поэтому сообщения об ошибках (если они сами по себе недоста
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
57
точно ясны) размещаются в руководстве программиста по каждому продукту, в котором реализована поддержка этого языка.
Сложно формализовать это требование, но самое главное, что необходимо сделать в описании языка, - выразить и донести до читателя его основную идею. Можно скрупулезно описать все элементы языка или синтаксис, но если читатель не поймет, как в принципе ведет себя «исполнитель», которому адресован текст, написанный на этом языке, создавать работоспособные программы он не сможет. С языками разметки все, конечно, проще, но все равно, описывая их, приходится объяснять как устроен документ.
Описание языка должно быть самодостаточным. Составляя этот документ, невозможно полагаться на знание читателем других языков, даже широко распространенных. Недопустимо писать, что « оператор цикла в языке Ыть имеет такой же синтаксис, как в языке C++* и тем ограничиться или описать только имеющиеся отличия. Необходимо дать полноценное описание оператора со всеми вариантами и нюансами, как будто прежде человечество не создавало ничего похожего.
Описание каждого оператора или другого элемента должно сопровождаться отлаженными работающими примерами.
Вместе с тем, описание языка не должно превращаться в учебник по программированию для начинающих, во всяком случае, если не была поставлена такая задача. Примеры приводятся только для того, чтобы показать особенности синтаксиса, а не объяснить, для чего нужен, предположим, цикл с проверкой условия в конце, и как им пользоваться.
ГОСТ 19.506-79 дает следующую типовую структуру описания языка (очевидно, она ориентирована только на языки программирования, и не учитывает существование языков разметки):
•	общие сведения;
•	элементы языка;
•	способы структурирования программы;
•	средства обмена данными;
•	встроенные элементы;
•	средства отладки.
Полноценное описание языка программирования может быть разработано только автором, имеющим собственный опыт профессиональной разработки программ. Для описания языков разметки такой квали
58
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
фикации обычно не требуется. Необходимость ясно излагать общие принципы и описывать многочисленные требующие проверки детали делает описание языка наряду с руководством программиста одним из наиболее сложных, трудоемких и дорогих документов.
Приведем примерное содержание документа, описывающего язык «Ыть».
1.	Назначение и краткая характеристика языка <Ыть>
2.	Формат исходных текстов программных модулей
(а)	Что такое программный модуль
(Ь)	Формат программного модуля
(с)	Специальные символы, используемые в тексте программы
3.	Примитивные типы данных
4.	Оператор присваивания
5.	Выражения языка <Ыть»
(а)	Арифметические операции
(Ь)	Операция конкатенации
(с)	Логические операции
6.	Операторы и синтаксические конструкции
7.	Основные приемы работы
(а)	Обращение к свойствам и методам объектов
(Ь)	Передача параметров процедур и функций
(с)	Работа со сложными типами данных
8.	Исполнение процедур и функций
9.	Отладка
2.2.5.	Руководство администратора
Задачей данного руководства является обеспечение администратора системы возможностью управления ее функционированием. Оно не стандартизируется. Руководство администратора адресовано лицу, задача которого - обеспечить определенный порядок функционирования системы. Обычно администратор считается пользователем системы, однако, при этом он наделен как особыми обязанностями, так и необходимыми для их выполнения привилегиями.
Работа администратора многопользовательской системы, как правило, заключается в управлении учетными записями других пользователей, предоставлении им полномочий на доступ к данным и выполнение операций, а также в исправлении сделанных ими ошибок. Например, бывают автоматизированные системы, в которых вводить и редактировать данные может любой пользователь, а удалять - только администратор. Кроме того, администратор может заниматься ве
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
59
дением нормативно-справочной информации, загрузкой и выгрузкой данных, открытием и закрытием расчетных периодов (в биллинговых системах) и т. п. С этой точки зрения руководство администратора является системным документом и приобретает смысл только в условиях конкретной системы с живыми пользователями [25].
С другой стороны, системы часто создаются на основе тиражируемых программных продуктов или аппаратно-программных комплексов. В составе таких решений нередко поставляется программный компонент под названием «Администратор», предназначенный для управления системой после ее развертывания. Руководство пользователя по этому компоненту тоже может иметь заголовок «Руководство администратора». В этом случае оно представляет собой программный документ, уточненный при создании конкретной системы технологической инструкцией администратора.
В руководстве администратора системы обязательно должны быть описаны [25]:
•	назначение и порядок применения системы;
•	общие принципы и логика работы системы;
•	обязанности администратора и связанные с ними операции;
•	обязательность, регулярность и очередность выполнения всех операций;
•	порядок выполнения каждой операции;
•	проблемы в работе системы и способы их решения.
Руководство по административному модулю программного или программно-аппаратного комплекса содержит примерно те же сведения, но в более общем виде. Например, в нем должно быть объяснено, как создать учетную запись пользователя, но не может быть указано, когда это следует делать. Такая конкретика возникает только при внедрении продукта в некотором конкретном месте и отражается в технологических инструкциях или регламентах.
По методике и стилю изложения руководство администратора похоже на руководство пользователя. При этом, как правило, описание в нем строится от задач, а не от функций.
При составлении руководства администратора особое внимание следует уделить описанию системы прав доступа и логике их назначения пользователям. Практика показывает, что этот материал у большинства авторов получается наиболее запутанным.
60
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Структура руководства администратора существенным образом зависит от того, как устроена система, и какого обслуживания она требует.
Примерная структура руководства администратора системы [25] выглядит следующим образом.
1.	Назначение системы.
2.	Принципы функционирования системы.
3.	Обязанности и задачи администратора.
4.	Обслуживание системы:
•	настройка параметров работы системы;
•	ведение нормативно-справочной информации;
•	учетные записи пользователей и управление ими;
•	назначение пользователям прав доступа;
•	загрузка и выгрузка данных.
5.	Проблемы в работе системы и способы их решения.
Структура руководства по административному модулю программного или аппаратно-программного комплекса имеет следующий вид [25].
•	Общие сведения о комплексе.
•	Функционирование комплекса в рамках системы.
•	Интерфейс пользователя административного модуля.
•	Задачи по обслуживанию системы:
—	настройка параметров работы системы;
—	ведение нормативно-справочной информации;
—	учетные записи пользователей и управление ими;
—	назначение пользователям прав доступа;
—	загрузка и выгрузка данных.
• Типичные проблемы в работе системы и способы их решения.
В разделе 2 можно рассмотреть несколько наиболее типичных случаев применения комплекса и перечислить основные обязанности администратора системы в каждом из них.
Руководство администратора не следует путать с руководством системного администратора. Первый документ говорит о том, как организовать и поддерживать целевое применение системы, второй - как обеспечить ее техническую работоспособность. Приведем примерное оглавление руководства системного администратора.
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
61
Допустим, что одним из банков разработана автоматизированная система «Альфа». Таким образом, она представляет собой внутренний программный продукт, который внедряется и применяется территориальными подразделениями банка. Система включает в себя около десяти крупных функциональных подсистем. И одна из них - подсистема «Администрирование».
Введение
•	Назначение подсистемы
•	Возможности подсистемы
•	Требования к уровню подготовки пользователя
•	Необходимая эксплуатационная документация
1.	Принципы администрирования автоматизированной банковской системы «Альфа»
(а)	Структура банковской системы «Альфа» и место подсистемы «Администрирование» в ней
(Ъ)	Модель пользовательских полномочий
(с)	Пользователь подсистемы администрирования и его полномочия
2.	Условия применения
(а) Требования к обеспечению рабочего места администратора
3.	Сеанс работы с подсистемой
(а)	Начало сеанса работы с подсистемой
(Ь)	Завершение сеанса работы с подсистемой
4.	Пользовательский интерфейс подсистемы
5.	Описание операций
(а)	Назначение полномочий пользователям
i.	Управление учетными записями пользователей
А.	Общие сведения
В.	Просмотр списков пользователей
С.	Просмотр информации о пользователе и редактирование реквизитов учетной записи
D.	Создание учетной записи пользователи
Е.	Включение пользователя в группу пользователей
F.	Исключение пользователи из группы пользователей
ii	. Управление группами пользователей
А.	Просмотр списков групп пользователей
В.	Просмотр информации о группе пользователей и редактирование реквизитов группы
С.	Создание и удаление группы пользователей
D.	Назначение ролей группе пользователей
in. Управление ролями
А.	Просмотр списков ролей
62
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
В.	Просмотр информации о роли и редактирование реквизитов роли
С.	Создание и удаление роли
D.	Формирование списка полномочий роли
Е.	Экспорт и импорт ролей
(Ь)	Работа с источниками данных
(с)	Просмотр списка всех загруженных объектов
(d)	Просмотр списка всех загруженных операций
(е)	Просмотр списка администрируемых функциональных подсистем
(f)	Выполнение технологических операций
i.	Загрузка нормативно-справочной информации
А.	Обновление списка операций и объектов
В.	Обновление организационной структуры
(g)	Получение отчетов
Глоссарий
Предметный указатель
2.2.6.	Руководство оператора
Задачей данного руководства является обеспечение оператора возможностью выполнять свои обязанности в отношении системы (в состав которой входит программа) или каких-либо ее частей.
Оператор по характеру своего взаимодействия с программой во многом похож на пользователя. От последнего он отличается тем, что напрямую не решает никаких целостных прикладных задач. С другой стороны, в отличие от администратора и системного администратора оператор не занимается настройкой системы. Его работа заключается в оперативном обслуживании системы, в состав которой входит программа.
Например, в обязанности оператора биллинговой системы может входить ежедневный запуск программ для приема учетных данных от телекоммуникационного оборудования и ежемесячный запуск программы формирования счетов. В обязанности оператора системы потокового ввода анкет может входить проверка правильности распознавания текста и исправление ошибок. Оператор колл-центра принимает и переводит адресатам входящие звонки [25].
Таким образом, задача руководства оператора заключается в том, чтобы оператор мог четко сделать все, что от него требуется, и никогда или как можно реже оказывался перед необходимостью принимать
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
63
нетривиальные решения в отношении программы. В содержательной части его действия с такой же строгостью могут быть заданы регламентами или технологическими инструкциями.
С точки зрения содержания, руководство оператора может рассматриваться как упрощенный вариант руководства пользователя [25]. При этом в большинстве случаев в руководстве оператора приводятся не описания функций, а как можно более четко сформулированные процедуры решения отдельных задач.
Руководство оператора должно быть написано как можно более простым языком и давать как можно более четкие инструкции по выполнению предусмотренных операций. Можно сформулировать несколько рекомендаций, которые помогут сделать его таким.
•	Минимум теоретических введений и концептуальных разделов. Если теория все-таки необходима, она вся должна быть собрана в один раздел.
•	Минимум явных и неявных ссылок внутри документа. Описания повторяющихся при выполнении разных операций процедур по возможности лучше дублировать.
•	Минимум ветвлений при описании процедур. Никаких условий вида «если вы хотите». У оператора нет желаний, а есть обязанности.
Оператору важно понимать, все ли у него идет так, как надо. Поэтому необходимо описывать не только его действия, но и результаты таковых в случае успеха.
Типовая структура руководства оператора приведена в ГОСТ 19.505-79. Этот документ состоит из следующих четырех разделов.
•	Назначение программы.
•	Условия выполнения программы.
•	Выполнение программы.
•	Сообщения оператору.
В современных условиях в эту структуру целесообразно добавить раздел «Интерфейс пользователя», актуальный сегодня для большинства программ. В случае программ, предполагающих диалоговый режим работы, можно переименовать раздел «Выполнение программы» в «Выполнение операций» либо описать каждую операцию или группу операций в самостоятельном разделе первого уровня.
На оператора возложены определенные обязанности по обслуживанию системы. В случае внештатной ситуации или чрезвычайного
64
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
происшествия, одним из первых подозреваемых в случившемся станет оператор. Достаточно вспомнить, например, кто чаще всего оказывается виноват в крушениях самолетов. В первую очередь комиссию по расследованию происшествия заинтересует тот факт, все ли персонал сделал по правилам. Поэтому от руководства оператора требуется повышенная четкость изложения, а каждое описанное в нем действие оператора должно иметь очевидное содержание, а также внятно описанный, объективный и проверяемый результат.
Например, содержание руководства оператора для программы вычисления, отображения и архивирования некоторых значений может выглядеть следующим образом.
1.	Назначение программы
2.	Условия выполнения программы
(а)	Аппаратное обеспечение
(Ь)	Программное обеспечение
(с)	Квалификация оперативного персонала
3.	Выполнение программы
(а)	Запуск и завершение программы
(Ь)	Отображение измеренных параметров
(с)	Изменение уровней установок
(d)	Просмотр архивных данных
4.	Сообщения оператору
2.2.7.	Руководство пользователя
Руководство пользователя - один из основных программных документов. Невозможно представить себе хоть сколько-нибудь сложный прикладной программный продукт, который не был бы укомплектован им в той или иной форме. Задача руководства - обеспечить пользователям возможность в полном объеме самостоятельно освоить и применять программу.
Основная задача документа состоит в том, чтобы обеспечить пользователям возможность самостоятельно решать все основные задачи, на которые нацелена программа.
Руководство пользователя содержит полное описание программы с точки зрения целевого применения последней. В руководстве пользователя обязательно должны быть описаны [25]:
•	назначение программы;
•	основные задачи и возможности;
•	способ отражения предметной области в программе;
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
65
•	пользовательский интерфейс программы;
•	порядок решения основных пользовательских задач;
•	все функции программы и порядок их применения;
•	пользовательская настройка программы;
•	проблемы при использовании и способы их решения.
При документировании небольших программ в руководство пользователя часто включают инструкции по установке, настройке, администрированию, обновлению и прочему обслуживанию программы.
Никогда или почти никогда руководство пользователя не рассматривается в качестве учебного пособия по предметной области.
В зависимости от особенностей программы и целевой аудитории руководство пользователя по способу изложения материала может приближаться к учебнику или, наоборот, к справочнику. Порядок изложения материала в руководстве пользователя определяется пользовательской перспективой программы.
Если программа представляет собой инструмент, позволяющий решать практические задачи из некоторого конечного набора, в руководстве приводят типовые процедуры решения каждой из них. Например, пользователю почтового клиента необходимо знать, как написать и отправить сообщение, как загрузить новые сообщения с сервера, как ответить на сообщение и т. п. Каждое из этих действий можно разложить на последовательные элементарные шаги, во всяком случае, для типичных ситуаций.
В крупной программе подобных пользовательских задач может быть много. Руководство пользователя, построенное по принципу пользовательских задач, напоминает учебник, хотя, как правило, лишено присущего учебникам методического аппарата: проверочных заданий, вопросов, упражнений.
Если программа представляет собой среду, в пределах которой пользователь может решать задачи, поставленные им самостоятельно, руководство пользователя должно быть ближе к справочнику. В нем последовательно и систематично должны быть описаны все функции программы и порядок их применения.
Так, в руководстве пользователя по графическому редактору приводится описание всех графических примитивов, инструментов, фильтров, однако, там не будет напрямую сказано, как изобразить дерево, лошадь или самолет. Пользователь это либо умеет рисовать, либо нет.
66
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Возможны и другие пользовательские перспективы. Бывают программы, посредством которых пользователь контролирует состояние того или иного объекта, скажем, промышленной установки. Тогда руководство пользователя строится по принципу таблицы: сообщение программы - реакция или возможные действия пользователя.
Если пользователь применяет программу для решения задач в нетривиальных предметных областях, в руководство пользователя настоятельно рекомендуется включить концептуальный раздел. В нем должен быть описан реализованный в программе способ представления объектов реального мира, чтобы пользователь хорошо понимал, с какими из них и на каком уровне абстракции он может работать.
Из-за большого разнообразия программ сложно представить себе универсальную структуру руководства пользователя. В каждом конкретном случае она будет в основном определяться особенностями описываемой программы. Тем не менее, обычно структура руководства пользователя похожа на следующую.
•	Общие сведения.
•	Установка и первоначальная настройка.
•	Основные понятия и определения.
•	Интерфейс пользователя.
•	Работа с программой.
•	Пользовательская настройка.
•	Сообщения об ошибках.
Единый раздел «Работа с программой» часто заменяют несколькими последовательными разделами, описывающими крупные группы пользовательских задач или функций.
Руководство пользователя не предусмотрено отечественными стандартами на программную документацию (ЕСПД). Из описанных в ЕСПД ближе всего к нему по назначению и содержанию документ «руководство оператора». Однако надо понимать, что у оператора, который имеется в виду в ЕСПД, мало общего с пользователем в современном понимании. При написании данной документации можно пользоваться следующими стандартами: ГОСТ 34.201-89, РД 50-34.698-90, IEEE 1063-2001.
Например, руководство пользователя программного комплекса «Автоматизация производства» может выглядеть так.
1.	Введение: общая информация о ПК кАвтоматиэация производ-стван», принятые сокращения и обозначения
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
67
2.	Концепция системы
(а)	Функционирование системы
(Ь)	Основные понятия системы
(с)	Сетевой и клиентский варианты работы
(d)	Технологические средства разработки
3.	Работа с программным комплексом
(а)	Запуск и завершение программы, открытие и сохранение файлов
(Ь)	Работа с файлами баз данных
(с)	Настройка рабочей области программного комплекса
4.	Интерфейс приложения
(а)	Основное окно приложения
(Ь)	Вспомогательные окна
5.	Командный интерфейс
(а)	Общее устройство командного интерфейса
(Ь)	Построение глобального командного интерфейса
(с)	Сервисные возможности навигации
(d)	Порядок разработки командного интерфейса
6.	Работа с данными
(а)	Механизм блокировки данных
(Ь)	Механизм работы с транзакциями
7.	Ведение расчетов
(а)	Основные понятия
(Ь)	Планы расчетов
8.	Решение задач автоматизации бизнес-процессов
9.	Анализ данных и прогнозирование
10.	Механизмы обмена данными
(а)	Цели и задачи
(Ь)	Универсальные механизмы обмена данными
(с)	Распределенные информационные базы
11.	Инструменты разработки
(а)	Редакторы
(Ь)	Конструкторы
(с)	Работа с графикой
(d)	Локализация
12.	Отладка прикладных решений
(а)	Отладчик
(Ь)	Замер производительности
(с)	Механизм имитации задержек при вызове сервера
13.	Групповая разработка
14.	Внешние компоненты
15.	Приложения
68
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.2.8.	Руководство программиста
Задача руководства программиста - обеспечить программисту возможность решать задачи, которые могут быть перед ним поставлены в отношении этой программы. Целевая аудитория - программисты, сопровождающие программу или использующие ее в качестве платформы либо средства разработки при создании собственных программ.
Руководство программиста разрабатывают в трех случаях:
•	программный продукт по своему основному назначению является средой разработки или библиотекой (например, как Delphi или Qt);
•	комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (например, 1С);
•	программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками.
Можно представить себе и другие ситуации (например, программный продукт является операционной системой), но в жизни они встречаются значительно реже.
Очевидная задача руководства программиста - снабдить разработчика информацией, которой ему будет достаточно для создания на базе программного продукта собственных программ или систем. Еще один мотив создания такого документа - потребность разработчиков время от времени фиксировать состояние продукта, чтобы самим в нем не запутаться и не плодить в коллективе носителей «сакральных знаний».
Руководство программиста должно объяснять [25]:
•	как устроен «мир», в который погружают разработчика:
-	с какими объектами программист имеет дело;
—	где они находятся;
—	сколько времени существуют;
-	как они взаимодействуют между собой; какие из них он создает сам;
—	какие предоставлены ему изначально средой, фреймворком, библиотекой;
•	какие дополнительные средства разработки (кроме данного программного продукта) необходимы для создания приложения или
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
69
системы. Например, если программный продукт - это библиотека, то программисту потребуются компилятор (возможно, вполне определенный), некоторая среда разработки и прочий инструментарий;
•	среда, в которой функционирует приложение или система; минимальные требования к системе; дополнительные программные средства для запуска программы: фреймворки, рантаймы, интерпретаторы;
•	минимальное работоспособное приложение или минимальная работоспособная система; последовательность создания объектов и связь между ними;
•	компиляция работоспособного приложения или развертывание работоспособной системы.
Это основные вопросы, без ответов на которые программист не сможет нормально работать. Если не сообщить их ему в явном виде, он будет вынужден заняться исследованиями. Но есть еще много дополнительных вопросов: методика и техника отладки, стиль программирования и др.
Кроме теории руководство программиста должно содержать полные описания всех предусмотренных в программном продукте объектов. Если это функции, то должны быть приведены их краткие описания, если классы, то описания их интерфейсов и т.д.
Если программный продукт предполагает использование оригинального языка программирования и снабжен собственным компилятором или интерпретатором, в руководство программиста необходимо включить его описание. Если оно получается достаточно объемным, его выносят в отдельный документ, который так и называется: описание языка (программирования).
Важнейшие методические требования к теоретической части руководства программиста - логичность и последовательность изложения. В частности, в тексте обязательно должны быть соблюдены следующие правила [25]:
•	при вводе нового понятия мы опираемся только на те понятия, которые были введены ранее явно или считаются заведомо знакомыми читателю.
•	ввод каждого понятия должен быть чем-то обоснован.
70
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Основное требование при описании отдельных объектов - полнота описания каждого из них. В отличие от руководства пользователя, при составлении которого в принципе можно рассчитывать на догадливость читателя, который поглядит на интерфейс и сам разберется, руководство программиста описывает неочевидные вещи. Восполнять недостаток информации программисту придется анализом исходного текста, а если он не доступен, то тестированием <черного ящика» и отладчиком. Это намного более долгий процесс, чем исследование по меню и диалоговым окнам.
При описании объектов особое внимание следует уделять следующим аспектам [25]:
•	что обязательно должно предшествовать созданию и использованию объекта;
•	каковы побочные эффекты обращения к объекту;
•	особенности интерпретации объектом передаваемых ему данных;
•	физическое местоположение объекта.
Желательно для каждого объекта привести примеры использования, небольшие фрагменты кода, демонстрирующие:
•	создание объекта (если перед использованием его необходимо создать);
•	передачу объекту входных данных;
•	получение выходных данных и их интерпретацию.
Описания объектов можно вынести в отдельный том или документ под названием < Справочник программиста», можно сделать его гипертекстовым.
Между теоретической частью и справочником по объектам полезно поместить небольшой раздел, в котором рассматривается пример небольшого, но полноценного, с точки зрения используемой платформы, приложения. Пример должен быть таким, чтобы читатель смог самостоятельно воспроизвести это приложение, отладить его и запустить.
Структура руководства программиста, зафиксированная в ГОСТ 19.504-79, такова [25]:
•	назначение и условия применения программы;
•	характеристика программы;
•	обращение к программе;
•	входные и выходные данные;
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
71
• сообщения.
В современных условиях такая структура не несет в себе никакой пользы. По этому плану может быть описан отдельный объект, например, функция или класс. Составить типовую структуру руководства программиста на все случаи жизни невозможно. Она получится поверхностной и малополезной. Вместо этого приведем два примера структуры [25].
Полноценное руководство программиста может быть написано только автором, имеющим собственный опыт профессиональной разработки программ.
Руководство программиста может комплектоваться различными схемами, например, схемами базы данных, диаграммами классов, графами вызова функций.
Пример 1. Программный комплекс «Аналитик»
Программный комплекс «Аналитик» предназначен для создания аналитических и отчетных банковских систем. Он содержит набор специализированных компонентов, из которых разработчик конструирует приложение в визуальной среде. Программный код в случае необходимости можно писать на языке C++ (поэтому описание языка программирования не требуется). Программный комплекс разработан компанией «Альфа». Кроме руководства программиста в комплект документации входит исчерпывающий справочник по всем компонентам ПК.
Примерное содержание руководства программиста.
1.	Общие сведения
(а)	Сокращения
(Ь)	Назначение
(с)	Функциональные возможности
(d)	Условия применения
(е)	Требования к квалификации разработчика
2.	Прикладное решение и его компоненты
(а)	Архитектура ПК кАналитиквь. Понятие прикладного решения
(Ь)	Требования к прикладному решению
1.	Базовые требования
ii.	Требования к входным данным
iii.	Требовании и алгоритмам расчета данных iv. Требования к отчетам и набору каждого из них V. Требования к разграничению доступа и информационной безопасности
(с)	Компоненты прикладного решения
72
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
L Структура базы данных ii. Загрузка исходных данных iii. Организация пользовательского интерфейса iv. Работа пользователи с данными v. Обработка и расчет данных vi. Отображение данных
vii. Средства автоматической загрузки и обработки данных. Системный агент
(d)	Разграничение прав доступа в прикладном решении
i.	Роли пользователей
ii.	Профили пользователей
(е)	Жизненный цикл прикладного решения
3.	Пример прикладного решении
(а)	Постановка задачи. Определение требований к прикладному решению
(Ь)	Проектирование прикладного решения
i.	Проектирование структуры таблиц и процедур загрузки данных
ii.	Проектирование интерфейса пользователя
iii.	Проектирование процедур расчета и отчетов
(с)	Реализация прикладного решения
i.	Авторизации в ПК кАиалитикн»
ii.	Создание категории решений
iii.	Создание таблиц
iv.	Создание процедур загрузки данных
v.	Создание справочников и визуальных форм дли них
vi.	Создание процедур расчета на изыке хранимых процедур базы данных
vii.	Создание отчетов
viii.	Создание групп пользователей и создание главного меню для них
ix.	Создание процедуры автоматического обновления (загрузки) данных с помощью системного агента
(d)	Развертывание прикладного решения
(е)	Тестирование прикладного решения
(£) Усложнение задачи
(g) Дорабетка прикладного решения
i.	Создание интерактивного отчета
ii.	Создание интерактивной загрузки
iii.	Финальный этап внесения доработок в прикладное решение
Пример 2. Электронный банк. Клиент-серверный протокол Система <Электронный банк» предназначена для приема и проведения моментальных платежей при оплате услуг и перевода денеж
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
73
ных средств на лицевые счета вкладчиков. Центральный сервер системы принадлежит привилегированной группе, а пункт приема платежей может открыть любой желающий, установив у себя на компьютере (подключенном к Интернету) программу-клиент. Обмен данными между центральным сервером и программой-клиентом осуществляется по специальному протоколу. Протокол открытый, что позволяет различным организациям осуществлять перевод средств непосредственно из собственных систем. Протокол разработан компанией «Бета». Приведем оглавление руководства пользователя.
Введение
i.	Система «электронный банк»: клиент-серверный протокол. Назначение и обзор возможностей
ii.	Задачи протокола
iii.	Основные преимущества использовании протокола
1.	Реализации протокола (шлюз)
(а)	Общие сведении
(Ь)	Структура приложения
2.	Как работает шлюз
(а)	Регистрация и отчетность
i.	Регистрация ii. Отчетность
(Ь)	Обмен данными с сервером
i.	Структура пакета
ii.	Справочники
iii.	Порядок обмена пакетами
(с)	Цикл обработки операции
i.	Запрос операции
ii.	Очередь
iii.	Анализ ответа сервера
iv.	Нестандартные ситуации
3.	Спецификация протокола
(а)	Структурные элементы пакета
(Ь)	Заголовок запроса
(с)	Заголовок ответа
(d)	Пополнение счета
(е)	Покупка PIN-кода
(f)	Прерывание процесса обработки операции
(g)	Транзакционные свойства операции
(h)	Запрос на проведение нескольких операций
(i)	Справочник
(j)	Статус операции
74
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
1.	Примеры сообщений о статусе операций
ii.	Коды состояния находящихся в обработке или завершенных операций
(к)	Уведомления системы
4.	Глоссарий
Приложения
Приложение 1. DTD XML-запроса и комментарий
DTD XML-запроса
Комментарий
Приложение 2. DTD XML-ответа
Приложение 3. Правила расчета суммовых полей
Приложение 4. Примеры запросов и ответов сервера
2.2.9.	Руководство системного администратора
Если программа более-менее проста, пользователь может самостоятельно установить ее себе на компьютер. Поддерживать ее работоспро-собность, например, выполнить переустановку, если возникнут какие-нибудь проблемы, он тоже, как правило, в состоянии. Сложными, в том числе, серверными и сетевыми программными продуктами приходится заниматься квалифицированным специалистам, системным администраторам. Более того, во многих компаниях сотрудникам запрещено устанавливать на своих рабочих местах программы по своему усмотрению. Даже простые программы там ставит только системный администратор.
В обязанности системного администратора также входит поддержание работоспособности программ, используемых в рамках тех или иных систем. Эта деятельность может заключаться в периодической проверке логов, резервном копировании данных, замерах производительности, устранении различных технических проблем.
Руководство системного администратора - программный документ, предоставляющий специалисту информацию, необходимую для выполнения этой работы. Следовательно, задачей данного руководства является обеспечение системного администратора возможностью самостоятельно установить программу и поддерживать ее функционирование в системе.
В ЕСПД специалист, сходный по обязанностям с современным системным администратором, называется системным программистом, а
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
75
адресованный ему документ - руководством системного программиста.
Руководство системного администратора - вспомогательный документ для прикладных программных продуктов и основной для серверных и системных, не имеющих непосредственных пользователей.
В случае небольших монолитных программ руководство системного администратора может оказаться документом небольшим по объему и простым по структуре. Руководство системного администратора на программный или аппаратно-программный комплекс, как правило, ощутимо сложнее, поскольку в нем приходится описывать каждый компонент по отдельности и способы их интеграции как друг с другом, так и со сторонним программным обеспечением: серверами баз данных, почтовыми серверами, антивирусами, средствами шифрования и пр. (далее для простоты будем везде писать «программа», имея в виду как неделимую программу, так и комплекс, включающий в себя ряд взаимодействующих программных компонентов).
Итак, в руководстве системного администратора должны быть изложены [25]:
•	назначение и область применения программы (или комплекса);
•	состав программы, основные принципы ее функционирования;
•	комплект поставки (если он не указан в отдельном документе);
•	системные требования для программы или ее компонентов;
•	предпочтительная очередность установки компонентов;
•	процедура установки программы или каждого ее компонента;
•	порядок обязательной первоначальной настройки программы;
•	способы интеграции установленных копий компонентов между собой;
•	интеграция программы со сторонним ПО, например, с сервером БД;
•	способы и периодичность контроля правильности работы программы;
•	порядок текущего обслуживания работающих копий программы;
•	порядок решения всевозможных вспомогательных задач;
•	аварийные ситуации и способы их устранения.
Данный список не является исчерпывающим. Нередко в руководстве системного администратора приходится описывать:
•	пользовательский интерфейс административной консоли;
76
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	утилиты командной строки и синтаксис их запуска;
•	конфигурационные файлы и правила их написания;
•	язык для составления управляющих скриптов.
Особенности установки зависят от того, какие средства для установки и настройки программы реализовали ее разработчики, какие именно инструменты даны в руки системному администратору. На методику изложения материала в руководстве системного администратора сильно влияет способ управления программой. Если большинство задач решается через административную консоль с графическим интерфейсом, то документ будет больше похож на руководство пользователя или руководство администратора. Если системному администратору придется активно составлять конфигурационные файлы и писать скрипты, документ будет ближе к руководству программиста или описанию языка программирования.
Структура руководства системного программиста, приведенная в ГОСТ 19.503-79 [25] и состоит из следующих разделов:
•	общие сведения о программе;
•	структура программы;
•	настройка программы;
•	проверка программы;
•	дополнительные возможности;
•	сообщения системному программисту.
Приблизительная современная структура руководства системного администратора [25] имеет вид:
•	общие сведения о программе (комплексе);
•	архитектура и принципы функционирования;
•	системные требования;
•	установка программы (комплекса);
•	административная консоль и работа с ней;
•	файл конфигурации. Составление и правка;
•	обязательная начальная настройка программы (комплекса);
•	проверка правильности функционирования программы (комплекса);
•	мероприятия по текущему обслуживанию программы (комплекса);
•	оптимизация работы программы (комплекса);
•	аварийные ситуации и способы их устранения.
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
77
Если речь идет о сложных программных или аппаратно-программных комплексах, то системный администратор - это квалифицированный специалист, которому приходится принимать нетривиальные решения. Чтобы удовлетворить его потребности в информации, составителю документации необходимо понимать, как мыслит его читатель, что и в какой момент может его заинтересовать, какая подробность изложения материала будет достаточной для него. Поэтому разрабатывать руководство системного администратора должен либо его коллега, имеющий навыки технического писателя, либо технический писатель, имеющий хотя бы небольшой опыт работы системным администратором.
Пример. Программа «ЯБухгалтер». Сетевая версия. Руководство системного администратора. «ЯБухгалтер» - одна из программ автоматизации бухгалтерского учета. Сетевая версия программы позволяет организовать совместную работу нескольких бухгалтеров с общим набором данных. Клиент-серверная архитектура и применение протокола TCP/IP для обмена данными между клиентской и серверной частями делает возможной работу бухгалтеров в режиме удаленного доступа (например, из дома). Приведем содержание руководства администратора.
ВВЕДЕНИЕ
i.	Краткое содержание
ii.	Терминология и условные обозначения
iii.	Техническая поддержка
iv.	Требования к конфигурации аппаратуры и программного обеспечения
v.	Требования к квалификации администратора
1.	СЕТЕВАЯ ВЕРСИЯ ПРОГРАММЫ И ПРИНЦИПЫ ЕЕ РАБОТЫ
(а)	Назначение сетевой версии программы
(Ь)	Базовые понятия и определения
L План сервера
ii.	Базы данных и табличные журналы
iii.	Структура баз данных
iv.	Схемы доступа
V. Пользователи
(с)	Порядок работы с сетевой версией программы
(d)	Необходимое условие корректной работы сетевой версии программы
78
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.	УСТАНОВКА СЕРВЕРА ЯБУХГАЛТЕР
3.	ПОЛЬЗОВАТЕЛЬСКИЙ ИНТЕРФЕЙС СЕРВЕРА
(а)	Запуск программы ЯБухгалтер-Сервер
(Ь)	Главное окно
(с)	Меню
(d)	Панель инструментов
(е)	Строка состояния
(f)	Список пользователей
4.	НАСТРОЙКА ПЛАНА СЕРВЕРА
(а)	Порядок выполнения настройки. Редактор плана сервера
(Ь)	Настройка баз данных, табличных журналов и их разделов
(с)	Структура баз данных: редактирование и реорганизация
(d)	Настройка схем доступа
(е)	Настройка перечня пользователей
(f)	Завершение работы с редактором плана сервера
5.	УСТАНОВКА СВЯЗИ СЕРВЕРА С КЛИЕНТСКИМИ РАБОЧИМИ МЕСТАМИ
(а)	Подключение клиентских мест к Серверу ЯБухгалтер
(Ь)	Отладка связи между клиентскими местами и программой-сервером. Основные неполадки и способы их устранения
6.	УПРАВЛЕНИЕ РАБОТОЙ КЛИЕНТСКИХ МОДУЛЕЙ С СЕРВЕРА
(а)	Просмотр изменений, вносимых пользователями в данные
(Ь)	Отправка сообщений пользователям
(с)	Закрытие клиентских мест
(d)	Отключение клиентских мест
(е)	Потеря связи с клиентским местом
7.	ВЗАИМОДЕЙСТВИЕ ПОЛЬЗОВАТЕЛЕЙ С ПРОГРАММОЙ-СЕРВЕРОМ
(а)	Отключение от программы-сервера
(Ь)	Типичные неполадки при взаимодействии пользователя с программой-сервером
8.	ОПТИМИЗАЦИЯ И НАСТРОЙКА ПРОГРАММЫ-СЕРВЕРА
(а)	Подготовительные и заключительные операции
(Ь)	Проверка наличия связи
(с)	Режим регистрации изменений записей общих данных
(d)	Пароль администратора сервера
(е)	Дополнительные параметры
9.	ВЕДЕНИЕ РЕЗЕРВНЫХ КОПИЙ (ЗЕРКАЛИРОВАНИЕ) ВАЗ ДАННЫХ
(а)	Понитие и порядок зеркалировании
(Ь)	Настройка зеркалирования
(с)	Экспорт зеркалирования баз данных
(d)	Импорт зеркалирования баз данных
2.2. ДВА ВИДА ДОКУМЕНТАЦИИ НА ПС
79
ПРИЛОЖЕНИЯ
Приложение А. Перенос баз данных и табличных журналов на сервер
Приложение В. Возможности работы в глобальных сетях
СПИСОК ИСПОЛЬЗУЕМОЙ ЛИТЕРАТУРЫ
УКАЗАТЕЛЬ
ГЛОССАРИЙ
2.2.10.	Справочная система
Справочная система предназначена для оперативного предоставления пользователю, оператору, администратору, системному администратору необходимых сведений о программе непосредственно во время работы с ней [25]. Стандарт, используемый при написании справочной системы - ISO/IEC 26514:207.
Полноценная справочная система состоит, по крайней мере, из двух частей: общей и контекстной.
В общую часть обычно включают материал всех имеющихся руководств: пользователя или оператора, администратора, системного администратора и других документов при наличии таковых. Более того, материал, который из-за большого объема невыгодно печатать на бумаге или неудобно искать в линейном документе, нередко включают только в справочную систему. В особенности это касается описаний библиотек функций и классов. Таким образом, получается электронная энциклопедия по программе или программно-аппаратному комплексу. Удобство ее еще и в том, что большинство форматов справки (и, следовательно, большинство просмотровых программ) позволяет снабдить справку удобными средствами навигации и поиска, в том числе, полнотекстового. Многие авторы не включают в справочную систему разделы, ознакомление с которыми, по логике вещей, предшествует работе с программой: системные требования, установка программы и т. п.
В контекстную часть справочной системы включают:
•	описание каждого режима и диалогового окна;
•	подсказки по элементам главного окна, окон документов и диалоговых окон;
•	подсказки по пунктам меню и кнопкам панелей инструментов;
•	подсказки по употребляемым терминам.
80
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Общей частью читатель пользуется как электронной книгой.
Разделы контекстной части связывают с определенными элементами интерфейса, что требует координации, (как правило, несложной) действий автора справки и разработчиков программы. Когда пользователь запрашивает справку, на экран автоматически выводится раздел, связанный с активным элементом. Таковым может оказаться верхнее диалоговое окно, элемент интерфейса, на котором находится фокус ввода, элемент интерфейса, на который пользователь навел указатель мыши и т.д. В разных операционных системах, графических оболочках и прикладных платформах способы запроса справки, вообще говоря, могут быть оригинальными. На практике пользователю везде предлагается примерно один и тот же набор возможностей и методов доступа к справке.
Многие форматы давно позволяют включать в справочные системы мультимедийную информацию: звуковые и видео-файлы, а также ролики Flash.
Справочная система - это гипертекст. Он не предполагает последовательного чтения. Читатель может выполнить поиск, и в результате получить доступ к произвольному (с точки зрения автора) разделу гипертекста. Составляя тот или иной раздел, автор не может рассчитывать на то, что читатель уже усвоил материал предшествующих разделов или хотя бы осведомлен об их существовании. Поэтому [25] следует руководствоваться перечисленными правилами.
•	Следует стремиться к тому, чтобы каждый раздел представлял собой самодостаточную статью, при ограниченном объеме в целом (пускай не стопроцентно) понятную читателю в отрыве от остального материала.
•	Если полное понимание раздела невозможно без ознакомления с некоторыми другими разделами справки, на них должны быть сделаны ссылки. Также настоятельно рекомендуется делать ссылки на определения терминов, употребляемых в тексте раздела.
•	В гипертексте исключены (поскольку лишены смысла) неявные ссылки из одного раздела в другой, которые в линейном тексте делаются с помощью выражений «как было сказано выше», «как будет показано ниже» и т.п.
2.3. ОРГАНИЗАЦИЯ ДОКУМЕНТИРОВАНИЯ ПС
81
•	Тем не менее, на практике справочная система часто представляет собой текст руководства пользователя, представленный в определенном электронном формате.
2.3. Организация документирования программных средств
Ошибки нельзя исправлять, их надо описывать в документации как особенности программы...
(Народная мудрость)
Документация является органической, составной частью программного продукта для ЭВМ, и требуются значительные ресурсы для ее создания и применения. Тексты и объектный код программ для ЭВМ могут стать программным продуктом только в совокупности с комплексом документов, полностью соответствующих их содержанию и достаточных для его освоения, применения и изменения [3]. Для этого документы должны быть корректными, строго адекватными текстам программ и содержанию баз данных. Они должны быть систематически, структурированно и понятно изложены, для возможности их успешного освоения и использования достаточно квалифицированными специалистами различных рангов и назначения. Качество и полнота отображения в документах процессов и продуктов в жизненном цикле программных средств должны полностью определять достоверность информации для взаимодействия заказчиков, пользователей и разработчиков, а тем самым корректность функций и достигаемое качество программных продуктов и соответствующих систем. Посредством документов (электронных или бумажных) специалисты взаимодействуют с программными средствами и данными в реализующих их вычислительных машинах, а также между собой.
Существует большая разница между тем, чтобы просто написать и запрограммировать некоторую функцию для индивидуального использования ее разработчиком, и тем, чтобы изготовить ее как качественный программный продукт, отчуждаемый от разработчиков, поставляемый заказчику и пользователям. Создание программного продукта требует значительных организационных усилий, ибо ее доку
82
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
ментация - это сложный живой организм, подверженный постоянным изменениям, которые могут вноситься многими специалистами. Управление документацией должно непрерывно поддерживать ее полноту, корректность и согласованность с программным продуктом. Необходимо обеспечивать возможность достоверного, формально точного общения всех участников проекта ПС между собой, с создаваемым продуктом и с документами для гарантии поступательного развития, совершенствования и применения комплекса программ. Адекватность документации требованиям, состоянию текстов и объектных кодов программ должна инспектироваться и удостоверяться (подписываться) ответственными руководителями и заказчиками проекта. Ошибки и дефекты документов не менее опасны для применения ПС, чем ошибки в структуре, интерфейсах, файлах текстов программ и в содержании данных. Поэтому к разработке, полноте, корректности и качеству документации необходимо столь же тщательное отношение, как к разработке и изменениям текстов программ и данных [3].
Документы в жизненном цикле программных средств отражают сущность процессов и продуктов, доступную для анализа, освоения и изменения участниками и пользователями результатов проектов. Поэтому организация, планирование, формирование и реализация регламентированных требований к структуре и содержанию документов ПС являются определяющими значительную часть успеха при создании и применении сложных программных продуктов. Наибольшее влияние на качество документирования комплексов программ оказывают: класс программного средства, его масштаб, связь с реальным масштабом времени и степень использования готовых апробированных компонентов. Эти показатели являются основой для выбора технологической среды разработки, а также номенклатуры, структуры и содержания документов. При этом возникает ряд организационных, методологических и технологических проблем и задач, которые должны решаться при подготовке процессов документирования проектов программных средств.
Возникают следующие проблемы определения потребности документирования программных средств, которые следует решать в проектах, начинаются с анализа, с целью понять каждую решаемую проблему до начала разработки проекта и комплекса документов программного средства [1]:
2.3. ОРГАНИЗАЦИЯ ДОКУМЕНТИРОВАНИЯ ПС
83
•	выявление заинтересованных лиц и пользователей документов, чье коллективное мнение в конечном итоге определяет успех или неудачу проекта и его документации;
•	определение, приблизительного местоположения функций, областей и границ решения проблем документирования ПС;
•	достижение соглашения с заказчиком по определению наличия и содержания конкретных проблем создания документов для жизненного цикла программного продукта;
•	выделение основных причин и источников, определяющих появление проблем документирования;
•	понимание ограничений, которые могут сопутствовать или препятствовать решению проблем документирования.
Для анализа этих проблем применяются методы системной и программной инженерии, позволяющие осуществить разбиение сложной системы на подсистемы [1]. Они помогают понять, где должны находиться программные средства и документы, а также каким общим целям системы они служат.
2.3.1.	Процесс документирования
Процесс документирования предусматривает формализованное описание информации, созданной в течение жизненного цикла ПС.
Он содержит набор действий, с помощью которых планируют, разрабатывают, выпускают, редактируют, распространяют и сопровождают документы, необходимые для всех заинтересованных лиц: пользователей ПС, разработчиков, менеджеров и т.п.
Процесс документирования ПС входит органически во все этапы жизненного цикла ПС. Этот процесс состоит из следующих действий.
1.	Подготовительная работа. На данном этапе решаются следующие задачи.
•	Разработка плана, идентифицирующего документы, которые должны быть произведены в течение жизненного цикла ПС.
•	Для каждого идентифицированного документа должны быть определены:
—	заголовок или название;
—	цель;
84
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
—	предназначенная аудитория;
—	процедуры и обязательства для ввода, разработки, обзора, модификации, утверждения, производства, хранения, распределения, сопровождения и управления конфигурацией;
—	план, режим, программа для промежуточных и заключительных версий.
2.	На этапе Проектирования и разработки каждый документ должен быть спроектирован (разработан) согласно соответствующим документационным стандартам. Должны быть подтверждены источники и соответствие входных данных для документов. Подготовленные документы должны быть рассмотрены и отредактированы на предмет формата, технического содержания и стиля представления в соответствии со стандартами. Документы должны быть одобрены доверенным персоналом до выпуска.
3.	При выпуске документации она должна быть произведена и поставлена согласно плану. Производство и дистрибуция документов может использовать бумагу, электронные или другие средства. Оригинал должен быть сохранен согласно требованиям для хранения данных, защиты, содержания и дублирования. Средства управления должны быть поставлены согласно процессу управления конфигурации.
4.	Сопровождение. Задачи, требующие исполнения измененного кода, представленного в документации, должны быть выполнены в соответствии с процессами сопровождения ПС. Для тех документов, которые находятся под конфигурационным управлением, модификации должны управляться в соответствии с процессами управления конфигурацией.
Организация работ по документированию ПС в значительной степени определяет стратегию, стандарты, процедуры и планы создания, изменения и применения документов на ПС.
Методы и средства документирования каждой процедуры в стандартах обычно не раскрываются и адресуются к специальным нормативным документам различного уровня [3]. Быстро оснащающиеся различными методами и инструментальными средствами этапы системного анализа, моделирования и проектирования ПС различных классов и назначения затрудняют стандартизацию этих процессов, до-
2.3. ОРГАНИЗАЦИЯ ДОКУМЕНТИРОВАНИЯ ПС
85
статочную для полной формализации структуры и содержания документов на программы и данные на уровне международных стандартов. Поэтому для этих этапов создаются нормативные документы - шаблоны, использующие, адаптирующие и дополняющие компоненты стандартов в разумной степени. Такие нормативные документы содержат выделенные фрагменты стандартов ЖЦ ПС и других стандартов, регламентирующих шаблоны программных документов на различных этапах проекта. В результате создаются и применяются проблемно-ориентированные совокупности методических руководств, отражающие наиболее современные методы, формы и фрагменты документов для документальной поддержки этапов и процессов жизненного цикла ПС, определенного класса или функционального назначения [3].
Процессы документирования программ и данных входят в весь жизненный цикл сложных систем и ПС. Поэтому организация и реализация работ по созданию документов должны распределяться между специалистами, ведущими непосредственное и преимущественное создание проектов комплексов программ, и специалистами, осуществляющими в основном разработку, контроль и издание документов.
При создании особо сложных систем целесообразно выделение специального коллектива, обеспечивающего организацию и реализацию основных системных работ по документообороту ПС. Совокупные затраты на документирование крупных программных продуктов могут достигать 20-30% от общей трудоемкости проекта и необходимого числа (десятки) специалистов в жизненном цикле проекта ПС [3].
В более простых случаях организация работ может быть упрощена, затраты на документирование снижаются приблизительно до 10%, однако всегда целесообразно выделять специалистов, непосредственно ответственных за создание, адекватность и контроль полноценного комплекта документов на программный продукт. Состав и общий объем документов широко варьируются в зависимости от класса и характеристик объекта разработки, а также в зависимости от используемой технологии. Наиболее сложному случаю разработки критических ПС реального времени высокого качества соответствует самая широкая номенклатура документов. Такой перечень документов может быть использован как базовый для формирования на
86
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
его основе состава и шаблонов документов в остальных более простых проектах.
Базой эффективного управления проектом ПС и его документированием должен быть План, в котором задачи исполнителей частных работ согласованы с выделяемыми для них ресурсами, а также между собой по результатам и срокам их достижения [3]. План проекта должен отражать:
•	рациональное сочетание целей,
•	стратегий действий,
•	конкретных процедур,
•	доступных ресурсов и других компонентов, необходимых для достижения основной цели с заданным качеством.
Планирование реализации проектов и их документирования должно обеспечивать компромисс между характеристиками создаваемой системы и ресурсами, необходимыми на ее разработку и применение. Реализация плана зависит от результатов выполнения частных работ и документов и может требовать оперативной корректировки плана. Контроль обеспечивает исходные данные для координации элементов данной организации в соответствии с планом конкретной задачи. Для этого необходимо следить за ходом проекта и документирования на всем протяжении жизненного цикла и сравнивать запланированные и фактические результаты работ и документы. Контроль является органической функцией управления [3] и должен иметь ряд средств регулирования поведения отдельных специалистов и коллектива разработчиков документов в целом.
При подготовке этих планов целесообразно по возможности разделять их цели и функции. План управления разработкой следует ориентировать на организацию специалистов, непосредственно создающих компоненты и ПС в целом, на эффективное распределение и использование ими ресурсов и средств автоматизации. В Плане управления документированием и обеспечением качества ПС внимание специалистов должно акцентироваться на анализе достигнутых результатов разработки, методах и средствах достижения заданных заказчиком характеристик ПС [3]. При планировании и разработке комплекс документации должен проверяться и аттестовываться на полноту в условиях ограниченных ресурсов, на корректность, адекватность и непротиворечивость отдельных документов.
2.3. ОРГАНИЗАЦИЯ ДОКУМЕНТИРОВАНИЯ ПС
87
Различия в организационных службах и процедурах, методах и стратегиях приобретения ПС, масштабах и сложности проектов, требованиях систем и методах их разработки влияют на способы разработки, применения и сопровождения документов. Во многих предприятиях используются собственные нормативные шаблоны документов на процессы и продукты ЖЦ ПС, адаптированные к конкретным условиям разработки и характеристикам созидаемых ПС. В них выделяются состав и шаблоны документов, наиболее важные для проекта и качества создаваемого ПС, а также для конкретных заказчиков и пользователей. Соответственно определяются технологические и эксплуатационные документы, для которых регламентируются структура и основное содержание шаблонов документов.
Особое внимание в последнее время уделяется совершенствованию и детализации документов, обеспечивающих высокое качество создаваемых ПС [3], а также возможности их эффективного итерационного развития длительное время в многочисленных версиях. Соответственно должны изменяться документы, отражающие состояние процессов и компонентов проектов. Для этого организация процессов документирования должна обеспечивать гибкое и точное изменение документов - сопровождение и конфигурационное управление версиями и редакциями каждого документа.
Эти процессы и поддерживающие их средства автоматизации должны быть адекватными тем, которые применяются при сопровождении непосредственных объектов разработки - комплекса программ и данных. Они должны быть поддержаны организацией контроля, регистрации и утверждения версии каждого документа, в той степени и на том уровне, которые необходимы в данном проекте для определенного документа.
Для хранения, тиражирования и распространения документов, сложных ПС высокого качества следует выделять группу специалистов, ответственных за контроль, обеспечение и гарантированное сохранение документации. Для критических, важных систем документация на программы и данные должна храниться и дублироваться на различных типах носителей и эпизодически выводиться на бумажные носители. При определении схемы обеспечения сохранности документации разного содержания, следует учитывать ее важность, трудоемкость хранения и возможность аварийного восстановления. Кроме того, должна быть организована служба нормативно
88
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
го контроля, ответственная за соблюдение стандартов, нормативных и руководящих документов при подготовке документации всеми специалистами, участвующими в крупном проекте. Эта служба обязана обеспечить унификацию и высокое качество содержания, структуры и оформления шаблонов документов. Для обеспечения достоверных данных об объектах и процессах управления документами ПС необходима автоматизированная база данных — информационная система обеспечения и хранения документов проекта. Такая информационная система документооборота представляет собой комплекс формальных и неформальных каналов поэтапного обмена информацией и документами между участниками проекта.
Степень формализации документооборота в коллективе специалистов может варьироваться от утверждаемых руководителями планов, технических заданий и документов на компоненты и версии ПС до личных бесед между разработчиками [3].
2.3.2. Документирование корпоративной информационной системы
Под корпоративной информационной системой (КИС) или автоматизированной системой (АС)1 будем понимать решение, полностью или частично автоматизирующее деятельность некоторой организации. Заметим, что АС включает в себя и программы, и данные, и аппаратные средства, и участвующий в автоматизированных бизнес-процессах персонал [40, 43]. Иными словами, завершенная АС обязательно внедрена, она не продается <в коробке», хотя может создаваться на основе тиражируемого программного продукта.
Документирование АС обычно обусловлено следующими обстоятельствами.
•	Разные компоненты АС (модули, функциональные подсистемы) могут создаваться в разное время разными командами, что объясняется постепенным изменением потребностей бизнеса, необходимостью планирования бюджета и загруженностью разработчиков.
•	Документация на АС не сводится к технической документации на входящие в ее состав программы, обязательно должна быть 1
1 Налицо терминологическая проблема: в российской компьютерной периодике укоренился первый термин, а в ГОСТ серии 34 используется второй.
2.3. ОРГАНИЗАЦИЯ ДОКУМЕНТИРОВАНИЯ ПС
89
-	описана технология выполнения бизнес-процессов с помощью системы.
•	Постоянное изменение обстановки, в которой действует организация, вынуждает модифицировать АС и автоматизированные бизнес-процессы, при этом необходимо поддерживать актуальность документации.
•	Аудитория документации на АС, т.е. сотрудники, которые непосредственно работают с ней, а также обеспечивают ее эксплуатацию и сопровождение, могут быть распределены по территориально удаленным друг от друга офисам организации.
•	Документация на АС включена в документооборот организации, она может проходить согласование и утверждение, отдельные документы могут приобретать нормативное значение, выдаваться сотрудникам для ознакомления под роспись, предоставляться внешним и корпоративным аудиторам и т.п.
Это заставляет предъявлять к документации и процессу документирования противоречивые требования.
Такие документы, как формуляр, руководство администратора или руководство программиста, должны содержать необходимые сведения обо всех компонентах АС и взаимосвязях между ними. Если АС достаточно сложна, для каждой пользовательской роли разрабатывают отдельное руководство, причем одна и та же пользовательская роль может требовать обращения к разным компонентам. Вместе с тем, документирование компонентов АС - часть их разработки, а разрабатываются они по отдельности.
Пользователям должно быть удобно работать с документацией, а разработчикам сопровождать ее. В интересах первых руководства пользователя следовало бы объединить с описаниями бизнес-процессов, а в интересах вторых - вынести описания бизнес-процессов в отдельный документ.
Чтобы сотрудники всегда имели доступ к самой последней версии документации, ее рекомендуется публиковать на интранет-сайте, однако, нормативные и отчетные документы должны быть представлены твердыми копиями, оформленными согласно традиции или определенному стандарту.
Информация возникает и фиксируется в одном порядке, а потребляется в другом, причем разные аудитории нуждаются в разных фор-
90
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
матах ее представления. Следовательно, необходим механизм перегруппировки и дублирования информации.
Реализовать его можно, в частности, с помощью технологии единого источника. Информация о программном обеспечении, работающем с документацией по этой технологии, приведена в части 3. учебного пособия. Рассмотрим основные принципы работы данной технологии.
•	Документация составляется по предметам, а публикуется по аспектам. Вместе с каждым компонентом разрабатывается техническая документация на него. Сведения об устройстве и порядке администрирования компонентов включаются в соответствующие сводные документы. Если между пользовательскими ролями и компонентами нет взаимнооднозначного соответствия, то для каждой роли формируется руководство, включающее инструкции по работе со всеми необходимыми компонентами.
•	Техническая документация публикуется в нескольких форматах. Для поддержки ежедневной работы сотрудников создается HTML-публикация, а для изготовления твердых копий формируются PDF-документы.
•	Описания бизнес-процессов (технологические инструкции) разрабатываются отдельно от руководств пользователя. Для удобства чтения их связывают:
- перекрестными ссылками, преобразуемыми в гипертекстовые при формировании HTML-публикации;
— включающими ссылками, преобразуемыми непосредственно в текст при формировании PDF-документов.
2.3.3. Документирование комплектуемого решения
Комплектуемое решение поставляется потребителю в одном из возможных вариантов, количество которых комбинаторно. Типичный пример комплектуемого решения - РС-совместимыЙ компьютер. Он состоит из определенных функциональных блоков (корпуса, системной платы, процессора, модулей оперативной памяти, жесткого диска и др.), причем их модели и технические характеристики варьируются от поставки к поставке. В действительности сочетаемость блоков ограничена: одни должны присутствовать обязательно, другие могут быть взаимоисключающими или, наоборот, устанавливаться только
2.3. ОРГАНИЗАЦИЯ ДОКУМЕНТИРОВАНИЯ ПС
91
совместно, но для нас это сейчас не существенно. Важно, что эксплуатационная документация на такое решение тоже должна комплектоваться, поставлять ее в избытке практически невозможно, потому что избыточность получится огромной.
Далее для простоты изложения будем предполагать, что комплект эксплуатационной документации состоит из единственного документа, руководства по эксплуатации. Другие документы, например, паспорт или спецификация [41], формируются аналогично.
Простейший способ комплектации руководства по эксплуатации -создать шаблон с унифицированной структурой разделов и вручную заполнять его включающими ссылками на фрагменты единого источника. Эти ссылки содержат описания моделей блоков, поставляемых в составе конкретной конфигурации. У этого способа есть два весомых недостатка.
•	Во-первых, для каждой конфигурации фактически придется разрабатывать отдельный шаблон.
•	Во-вторых, технические характеристики конфигурации тоже придется указывать вручную, что ведет к тиражированию разделов, в которых они приводятся.
Очевидно, этот способ трудоемок и чреват многочисленными ошибками, особенно учитывая, что некоторые технические характеристики конфигурации зависят от моделей блоков, например, максимальный объем оперативной памяти - свойство системной платы.
Технически сложнее, но намного эффективнее сделать руководство пользователя параметрическим. Автор, публикующий руководство на очередную конфигурацию, не будет редактировать ни шаблон, ни фрагменты единого источника, вместо этого он укажет значения параметров конфигурации. При формировании выходного документа они автоматически подставятся в него.
Предусмотрены три категории параметров конфигурации.
1.	Структурный параметр содержит идентификатор (условное обозначение, принятое в рамках проекта) модели включаемого в конфигурацию блока определенного типа, допустим, корпуса или системной платы. По идентификатору фрагмент с описанием блока извлекается из единого источника при обработке входного документа. Если блок некоторого типа отсутствует в конфигурации, то соответствующему структурному параметру следует присвоить пустое значение.
92	2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.	Свободный параметр содержит значение, которое варьируется от конфигурации к конфигурации. Свободными параметрами могут быть, например, объем установленной оперативной памяти, емкость жесткого диска, тактовая частота процессора, гарантийный срок.
3.	Связанный параметр содержит значение, определяемое моделью какого-нибудь блока. Так, максимальный объем оперативной памяти, максимальное количество процессоров, габариты корпуса - связанные параметры.
Все значения структурных и свободных параметров указываются в едином файле конфигурации. Значения связанных параметров указываются непосредственно во фрагментах с описаниями блоков. Шаблон руководства, как обычно, содержит включающие ссылки на фрагменты единого источника, однако, они выражены через значения структурных параметров. Фрагменты единого источника могут содержать ссылки на параметры, иными словами, они экспортируют значения связанных параметров и импортируют значения свободных и связанных параметров.
2.4. Управление документированием этапов жизненного цикла программного средства
Лучший способ грамотно составить документ -это написать «бред» и дать на подпись начальнику.
(Евгений Скворцов)
Общее руководство процессом документирования комплексов программ можно разделить на два уровня [3]:
•	адаптация состава и содержания документов к данной деловой, проблемно-ориентированной области, например, авиационной, медицинской, военной, финансовой или административной;
•	адаптация номенклатуры, структуры и содержания документов для каждого специфического проекта, контракта или предприя-
тия.
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
93
2.4.1.	План выполнения документирования
В соответствии со стандартами план документирования в виде совокупности разрабатываться системными аналитиками и утверждаться менеджером проекта вместе со спецификацией требований к ПС. В спецификации формализуются требования к результатам документирования, а в плане - методы и средства их достижения. Тем самым характеристики ПС не только декларируются в виде требований, но и сопровождаются совокупностью рекомендуемых мероприятий и документов по их обеспечению и реализации.
Достоверность прогнозов требующихся ресурсов для документирования зависит, прежде всего, от точности оценки исходных данных. Такие оценки зависят от компетенции и объективности экспертов, их оптимистичности, пессимистичности и знания существенных особенностей проекта [3]. Оценивая масштаб, функции и требования к документации, заказчик и разработчики должны представлять тот объем затрат и физический размер комплекса документации, который придется создать в процессе всего жизненного цикла ПС, а также для обеспечения его эффективного применения.
Важнейшим фактором при оценивании затрат на документирование в ЖЦ ПС являются люди - специалисты, с их уровнем профессиональной квалификации, а также с многообразием знаний, опыта, стимулов и потребностей [1]. Быстрый рост сложности, повышение требований и ответственности за качество документов комплексов программ привели к появлению новых требований к специалистам, обеспечивающим все этапы жизненного цикла ПС. Каждый специалист ограничен в своих возможностях, способностях и квалификации, что отражается на специфических дефектах результатов и документах его деятельности. Специалисты в соответствии со своей квалификацией и ролью в проекте вносят в него специцфические дефекты и ошибки достаточно определенных категорий, что целесообразно учитывать при прогнозировании документов проекта.
Разработка и документирование сложных ПС, особенно, на начальных и завершающих этапах, характеризуется высокой долей творческого труда. Дефекты, трудоемкость и длительность отдельных операций и частных работ существенно зависят от индивидуальных особенностей их исполнителей и характеристик конкретного проекта. Отсюда принципиальной особенностью планирования документирования
94
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
комплексов программ является необходимость активного участия руководителей и заказчиков проектов в составлецнии планов на базе исследованных характеристик прототипов завершенных разработок ПС и их личного опыта.
Недостатки или отсутствие достоверного обоснования необходимых ресурсов для документирования проектов новых ПС, являются причинами острых конфликтов между заказчиками и разработчиками. Поэтому целесообразно активно привлекать заказчиков к управлению документированием проектов, чтобы обеспечить своевременность разработки ПС в условиях ограниченных ресурсов. Необходимы согласия заказчиков при принятии основных решений, и только они могут реально определить, как получить комплекс программ с необходимой документацией высокого качества, выполненный в срок и в пределах бюджета [1|.
При разработке комплексов программ большими коллективами велика роль квалификации руководителей разработки, что непосредственно отражается на интегральных дефектах и документах проекта ПС. Руководство крупномасштабным проектом ПС должны осуществлять один или два лидера - менеджера с различными функциями [1|:
•	менеджер проекта - этот специалист, обеспечивающий коммуникацию между заказчиком и проектной командой, его задача определять и обеспечивать удовлетворение требований заказчика с учетом согласованных с ним доступных ресурсов, и по возможности сокращать ошибки оценивания реальной сложности ПС и документов;
•	менеджер-архитектор комплекса программ и документации управляет коммуникациями и взаимоотношениями в проектном коллективе, является координатором создания компонентов, разрабатывает базовые, функциональные спецификации и управляет ими, ведет график проекта и отчитывается за его состояние, инициирует принятие критичных для хода проекта решений, которые могут содержать соответствующие типы ошибок документов планирования и системного проектирования ПС.
Менеджер проекта для оценок объема и содержания документации должен подготовить план выполнения документирования в жизненном цикле ПС [3]. Этот план должен содержать описания соответствующих работ и задач и обозначения создаваемых программных продуктов и документов. Он охватывает следующие задачи:
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
95
•	установление графиков и сроков своевременного решения задач документирования;
•	оценка необходимых трудозатрат на создание каждого документа и всего комплекса;
•	определение времени, необходимого для выполнения конкретных задач документирования;
•	распределение задач документирования по исполнителям;
•	определение обязанностей исполнителей по созданию содержания документов;
•	выделение критических ситуаций, связанных с задачами или самим процессом документирования;
•	установление критериев управления и обеспечение качества документов;
•	обеспечение внешних условий и определение инфраструктуры проекта системы для выполнения процесса документирования.
Менеджер программного проекта должен отвечать за проведение оценок программных продуктов, документов и планов: на соответствие принципам, методологии и технологии управления проектом и документированием; в части удовлетворения их установленным требованиям договора с заказчиком. Необходимыми компонентами успешной реализации программных проектов являются периодические анализы и оценки хода выполнения и завершения этапов и заданий на документирование [3].
Уровень квалификации заказчика и корректность технического задания на разработку ПС может весьма сильно влиять на выделяемые ресурсы при создании комплекса программ. По тем или иным причинам даже при испытаниях заказчик зачастую обнаруживает, что решаются не совсем те задачи и не совсем так, как нужно, вследствие чего необходима переработка готовых программ, что отражается большим ущербом вследствие дефектов исходных требований заказчика. При проектировании и создании высококачественных комплексов программ, прежде всего, необходима организация и тесное взаимодействие представителей заказчика и менеджеров разработчиков проекта. Взгляды и требования заказчика, в основном, итражак/тся в функциональных и потребительских характеристиках и документах ПС [1]. Устремления разработчиков направлены на возможность и способы их реализации с требуемым качеством. Эти различия исходных точек зрения на проект приводят к тому, что некоторые неформализованные
96
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
представления тех и других имеют зоны неоднозначности и взаимного непонимания, отражаюцщиеся на документах, что может приводить к конфликтам.
Разработчики должны иметь в своем составе квалифицированных, проблемно-ориентированных аналитиков и системных архитекторов, способных переводить функциональные требования заказчика в конкретные документы, спецификации и технических требования к комплексу программ и его компонентам. Им необходима высокая квалификация по архитектурному построецнию, комплексной отладке и испытаниям ПС определенных классов, умение организовать коллектив для решения общей целевой задачи системы. Это позволит на ранних этапах исключать или сокращать системные и алгоритмические дефекты документов, обусловленные различием представления ими целей и задач проектов, а также их показателей качества.
Затраты труда при реализации и документировании крупномасштабного проекта ПС полезно распределить по двум категориям специалистов:
•	разрабатывающим компоненты и ПС в целом;
•	обеспечивающим технологию и качество программного продукта и документов.
Организационное разделение специалистов, осуществляющих разработку ПС (первая категория), и специалистов, контролирующих и управляющих его качеством и документами в процессе разработки и всего ЖЦ (вторая категория), должно обеспечивать эффективное достижение заданных характеристик, а также независимый, достоверный контроль затрат ресурсов при разработке ПС.
2.4.2.	Планирование качества документов
Разделение труда специалистов в крупных проектных коллективах приводит к необходимости их дифференциации по квалификации и областям деятельности, каждая из которых характеризуется определенными типами документов и возможных дефектов [1]:
•	спецификаторы п-чдгсггавливают описания функций соответствующих компонентов с уровнем детализации, достаточным для корректной разработки текстов программ программистами и их интерфейсов, которые могут содержать преимущественно алгоритмические ошибки;
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
97
•	разработчики программных компонентов - программисты создают компоненты, удовлетворяющие спецификациям, реализуют возможности продукта, отслеживают и исправляют про дефекты и ошибки, при разработке сложных систем это требует детального знания методов, технологии и языков программирования, а также проектирования баз данных;
•	системные интеграторы сложных проблемно-ориентированных ПС работают над проектами, в значительной степени, отличными от программистов методами, на разных языках проектирования, используют различные средства автоматизации и имеют на выходе различные документы крупных компонентов и комплексов программ, с соответствующими системными ошибками документов проектирования;
•	тестировщики обеспечивают проверку функциональных спецификаций, систем обеспечения производительности, пользовательских интерфейсов, разрабатывают стратегию, выполняют и документируют тестирование для каждого компонента проекта ПС, должны быть административно независимыми от программистов и спецификаторов, характеризуются соответствующими уровнями оставшихся не выявленными программных, алгоритмических и системных ошибок документов;
•	управляющие сопровождением и конфигурацией, инструкторы интерфейсов отвечают за снижение затрат на модификаццию и сопровождение продукта, обеспечение максимальной эффективности разработчиков по взаимодействию компонентов и реализации версий ПС, принимают участие в обсуждениях пользовательского интерфейса и архитектуры продукта, что также не может быть без ошибок проектирования, планирования и документирования проекта;
•	документаторы процессов и объектов ЖЦ ПС обеспечивают подготовку и издание сводных обобщающих технологических и эксплуатационных документов в соответствие с требованиями стандартов и возможными дефектами документов.
Анализ и мониторинг характеристик, последствий и частоты выявленных дефектов в документах конкретного комплекса программ может служить ориентиром для оценки индивидуальной квалификации и качества работы определенных специалистов.
98
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Следствием такого анализа может быть выделение некоторых специалистов, отличающихся большим числом дефектов, для их замены и дополнительного обучения с целью сокращения числа ошибок соответствующего типа. Накопление, классификация и обобщение характеристик дефектов определенных классов документов позволяцет прогнозировать изменение ошибок по этапам развития жизненного цикла ПС, а также необходимое распределения состава и квалификации специалистов.
В проекте ПС должен быть определен базовый график выполнения работ в жизненном цикле, а графики создания отдельных документов должны быть связаны и согласованы с этим базовым графиком [3]. Менеджер каждого программного проекта должен стремиться по возможности использовать существующую организационную инфраструктуру документирования на предприятии. Должен быть определен механизм для разрешения или преодоления конфликтных ситуаций между менеджером всего проекта ПС и администратором процесса документирования на соответствующем уровне их полномочий по организационному управлению. Это положение является общим для всех контрольных этапов, связанных с выполнением договорных обязательств по вспомогательным процессам, поэтому необходимы синхронизация соответствующих планов и своевременное уведомление менеджера ПС о всех затруднениях, возникающих при выполнении соответствующих задач процессов документирования.
В интересах сокращения стоимости и улучшения качества стандарты и регламентируемый ЖЦ ПС рекомендуется адаптировать к характеристикам конкретного проекта. Соответственно сформированному жизненному циклу следует адаптировать состав документов конкретного проекта ПС.
Для адаптации состава и содержания документации должны быть определены характеристики окружения проекта, которые могут воздействовать на адаптацию документирования:
•	процессы жизненного цикла создаваемой системы;
•	требования к системе и программному средству;
•	организационные процедуры и стратегии документирования;
•	размер, критичность и функции основных компонентов системы;
•	количество задействованного в проекте персонала и сторон.
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
99
В плане управления документированием каждого этапа жизненного цикла ПС целесообразно фиксировать и документально оформлять [3]:
•	исходные данные (шаблоны), требующиеся для успешного выполнения данного этапа документирования проекта или компонента ПС;
•	контролируемые и документируемые данные о состоянии объекта и процесса разработки, регистрируемые после завершения этапа;
•	содержание процедур контроля состояния проекта и документов в процессе выполнения работ этапа;
•	критерии оценки результатов выполненных работ и качества отчетных документов при завершении этапа;
•	состав и содержание отчетных документов (шаблонов), представляемых для оценки состояния проекта, результатов завершенного этапа и работ и для использования на следующем этапе или при завершении проекта ПС.
Планирование качества документов в ряде стандартов принято отделять от планов непосредственного управления процессом создания комплекса программ. Для реализации планов качественного документирования должны быть созданы регламентирующие документы, охватывающие [3]:
•	процессы создания документов, отражающих качество программного продукта;
•	обязанности и ответственность специалистов за качество конкретных документов;
•	используемые ресурсы, обеспечивающие создание документов высокого качества;
•	требования к качеству конкретных документов и способы его контроля.
Реальные ограничения ресурсов, используемых в процессе разработки, квалификация специалистов, изменения внешней среды и требований заказчика объективно приводят к отклонениям реализации плана документирования от предполагавшегося. Величина таких отклонений в значительной степени зависит от принятой технологии разработки, от уровня и характеристик средств разработки, а также от средств автоматизации создания программ. Для своевременного обнаружения отклонений от плана документирования необходимо регулярно регистрировать результаты выполненных работ и их харак
100
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
теристики качества. Для реализации таких измерений целесообразно предусмотреть и согласовать с заказчиком специальный документ, регламентирующий правила корректировки плана обеспечения качества ПС, а также состава и содержания поддерживающей его документации.
Адаптация номенклатуры и содержания документов ПС к особенностям системы и пользователей может базироваться на выборе подходящих шаблонов из набора документов. В процессе адаптации состава и содержания документов должны быть учтены особенности пользователей, поддерживающего персонала, руководителей контракта, потенциальных покупателей. Процессы, работы, шаблоны и задачи ЖЦ должны селектироваться и включать в себя перечень документов, которые обязательно нужно разработать, и информацию о персональной ответственности за них [3]. Выбранные процессы, работы и задачи, не обеспечиваемые конкретными документами, следует оговаривать в самом контракте и утвержденном ЖЦ ПС. При адаптации документирования ПС необходимо также учитывать особенности проекта: стоимость, планирование, производительность специалистов, размеры проекта и интерфейс с человеком-пользователем. Все исходные данные и решения по адаптации номенклатуры, структуры и содержания документов должны быть документированы и утверждены руководством проекта вместе с обоснованием их целесообразности.
Для реализации на практике требований и планов документирования в жизненном цикле программных средств необходимы организационные мероприятия, гарантирующие участникам проектов определенную культуру, дисциплину разработки и применения документов. Такая организационная система должна обеспечивать специалистам разной квалификации и специализации возможность взаимодействия при решении требуемых комплексных задач для накопления, хранения и обмена упорядоченной информацией о состоянии и изменениях компонентов проекта. Формализованная в документах информация должна повышать ответственность специалистов за корректность ее содержания, оперативность формирования и изменения, качество процессов, трансформации и реализации в жизненном цикле ПС.
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
101
2.4.3.	Архитектура системы документооборота
Для этого в каждом проекте комплекса программ должен быть организован регламентированный процесс документооборота, обеспечивающий для коллектива специалистов единую среду разработки, изменения и утверждения документов, адекватных реальному содержанию объектного кода программ и текстовых данных файлов ПС [3]. Процесс организации и технологического обеспечения документооборота должен быть ориентирован на слаженную, коллективную работу различных профессионалов, объединенных единой целью создания требуемого заказчиком комплекса программ с заданными функциями и высоким качеством документации.
Каждый участник проекта в соответствии со своими функциональными обязанностями должен иметь доступ к необходимой для него корректной информации и ограничен возможностями обращения к несанкционированным для него данным. Должны быть упорядочены деловые коммуникации между специалистами разных категорий, управление динамическими процессами изменений и транспортировки документов между подсистемами документооборота.
Первоначально должен быть разработан проект архитектуры системы документооборота и руководство по ее применению, настроена выбранная СУБД на управление взаимодействующими подсистемами документооборота, с соответствующими комплектами выбранных шаблонов документов, с учетом класса и масштаба предполагаемого ЖЦ ПС. Шаблоны подсистем документооборота должны поэтапно заполняться реальными данными проекта от заказчика и разработчиков соответствующих квалификаций и контролироваться менеджерами проекта. При этом следует управлять динамикой процессов реализации процедур документооборота, регистрировать реальное использование ресурсов специалистов, текущее время выполнения процедур процессов ЖЦ ПС и оформления документов в подсистемах. В реальных проектах ПС возможны отклонения от такой линейной схемы двух типов [3]:
•	прерывание процессов документооборота и прекращения всей разработки после промежуточных этапов системного, предварительного или детального проектирования вследствие недостаточности ресурсов для его полной реализации или вследствие отказа
102
2 ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
заказчика продолжать данный проект при появлении альтернативного варианта программного продукта;
•	итерационный возврат на предшествующие подсистемы документооборота, а также на их компоненты и шаблоны для корректировки и уточнения, обусловленные изменениями компонентов ПС.
При наличии адекватных прототипов и ряда детальных спецификаций требований, для создания новой базовой версии программного продукта может отсутствовать необходимость ее системного, предварительного или детального проектирования, а разработка и тестирование новых программных компонентов выполняться в процессе расширения функций предшествовавшей базовой версии. Тем самым процессы и руководства документооборота при развитии и совершенствовании версий ПС могут формализоваться, начиная с некоторых промежуточных этапов жизненного цикла комплекса программ.
В состав базовых версий программного продукта входит седьмая подсистема документооборота и комплект документов пользователей [3]. Этот комплект и содержание документов также следует адаптировать в соответствии с требованиями и характеристиками проекта. В системах реального времени в ряде случаев могут отсутствовать документы административного управления, а также сокращены в шаблонах требования и функции оперативных пользователей. В комплексах программ административных систем может доминировать документооборот администраторов, действующих совместно с оперативными пользователями при реализации основных функций программного продукта. В некоторых автоматизированных системах реального времени программный продукт является органическим компонентом системы управления и внешней среды, и эксплуатационная документация должна отражать в основном контрольные функции, инсталляцию и оценки целостности функционирования программного продукта в системе.
Состав комплекта технологических и эксплуатационных документов жизненного цикла базовой версии сложного программного средства реального времени, создаваемого «с нуля» приведен в качестве семи подробных таблиц в [3]. По ряду работ (например, программирование компонентов) в ЖЦ ПС рекомендуется использовать специфические документы, детально регламентирующие содержание и применение определенных технологических про
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
103
цедур в соответствии с инструкциями использования инструментальных средств. Детальную структуру каждого документа целесообразно уточнять менеджерам предприятия или проекта, в соответствии с их традициями, используемой технологией и особенностями проектируемого программного продукта. Формализованная структура и типовое содержание каждого документа должны позволять контролировать результаты и качество выполненных работ.
Представленный в [3] перечень документов в реальных проектах может варьироваться в зависимости от класса, масштаба и характеристик ЖЦ программного средства. Наиболее сложному случаю разработки крупномасштабных критических ПС реального времени высокого качества соответствует номенклатура и детализация всего комплекта представленных документов. Для каждого этапа жизненного цикла выделены три уровня сложности проектов ПС: особо сложные (свыше 200 тысяч строк - крупные), средние по масштабу (свыше 50 тысяч строк - средние) и небольшие проекты программных средств (малые).
При выборе заказчиком надежного поставщика-разработчика проекта необходима оценка тематической и технологической квалификации возможного коллектива специалистов, а также его способности реализовать проект с заданными требованиями и качеством документации. Тематическую квалификацию специалистов в области создания ПС определенного функционального назначения приближенно можно характеризовать средней продолжительностью работы в данной проблемной области основной части команды, непосредственно участвующей в разработке алгоритмов, спецификаций, программ, баз данных и документов. Важнейшую роль играет комплексная квалификация руководителей - менеджеров разработки и системных аналитиков функциональных компонентов, и в меньшей степени непосредственных разработчиков программ в конкретной прикладной области. Особенно важна не индивидуальная характеристика каждого специалиста, а, прежде всего, интегральный показатель квалификации «команды», реализующей некоторую, достаточно крупную функциональную задачу или весь проект. При низкой тематической квалификации допускаются наиболее грубые системные ошибки, требующие больших затрат при доработке программ или даже делающие проект практически не реализуемым [1].
104
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Дня сокращения и устранения дефектов документов проекта посредством адекватных контрмер необходима четкая организация коллектива специалистов и автоматизация процессов исправления дефектов, которые позволяют избегать множества вторичных ошибок, обусловленных недостаточной координацией проводимых корректировок и формирования новых версий сложных ПС и документов [1]. Этому должна способствовать утвержденная дисципцлина и иерархия принятия решений на координированные изменения компонентов и ПС в целом, должностными лицами проекта, поддержанная методами и средствами защиты от несанкционированного доступа при выполнении корректировок документов специалистами различной квалификации и права доступа к модификациям компонентов на разных уровнях проекта.
На основе проведенного анализа персонал разработки должен разрабатывать варианты реализации изменений и документально оформлять: сообщение о каждом дефекте или заявку на внесение изменений; результаты их анализа и варианты реализации изменецний, оценку их влияния на функциональную пригодность. Следует согласовывать с заказчиком выбранные варианты изменений документов в соответствии с договором. Регистрация и учет истории этого процесса обеспечивает возможность его контроля и пошагового восстановления выполненных изменений (отката) документов для выявления вторичных дефектов, внесенных в процессе разработки очередной версии. Такие дефекты обычно обусловлены одновременным, не скоординированным внесением групп изменений документов несколькими специалистами или потерей некоторых коррекцтировок в определенной версии ПС.
Если предполагается, что программный продукт будет иметь длительный, жизненный цикл поддержки или ожидаются значительные корректировки в ЖЦ ПС, то следует рассмотреть и учесть наиболее детальные требования к методике организации и к коллективу ответственному за совершенствование и документирование программ. В стратегии сопровождения документов следует учесть характеристики системы: количество компонентов программного средства, типы, размер, критичность и безопасность создаваемых и применяемых программных продуктов и документов. Для конкретного проекта они должны быть определены и зафиксированы в «Программе управления конфигурацией ПС».
2.4. УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
105
2.4.4.	Конфигурационное управление документацией
Управление конфигурацией ПС - это процессы (см. стандарты ISO 12207, ISO 15846, ISO 14764):
•	оценивания состояния версий программных средств, их дефектов и документов;
•	идентификации, определения и базирования конфигурации компонентов и документов в системе;
•	планирования процедур управления конфигурацией ПС и его компонентов;
•	управления, модификацией и выпуском версий программных продуктов и документов.
Цель конфигурационного управления документацией при создании сложных систем - обеспечить управляемое и контролируемое развитие их структуры, состава компонентов и функций, а также сокращение дефектов в течение всего жизненного цикла ПС и документов. Сложные системы состоят из многих компонентов (единиц конфигурации), каждый из которых может иметь разновидности или версии. В процессе организации конфигурационного управления необходимо построить и использовать компактные и наглядные схемы однозначной иерархической идентификации и изменения компоненте и документов ПС [1J:
•	объектов - модулей и компонентов ПС разного уровня интеграции, подвергающихся корректировкам (систему идентификации адресации изменений в комплексе программ и в документах);
•	корректировок содержания и взаимодействия проводимых изменений, которая должна обеспечивать возможность однозначного контроля, истории развития модификаций компонентов любого уровня, во времени и в пространстве элементов версий комплекса программ (типы, содержание и взаимосвязь корректировок документов);
•	специалистов, участвующих в конфигурационном управлении и сокращении дефектов, их права на доступ к определенным компонентам ПС и документам на конкретных стадиях разработки, реализации и утверждения изменений.
В процессах совершенствования сложных ПС и документации участвует большое число специалистов различных направлений и ква
106
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
лификации, которые при необходимости могут объединяться в единый коллектив [1] - службу сопровождения, управления конфигурацией программного продукта и документов. Менеджер проекта является высшим должностным лицом, принимающим важнейшие решения по внесению изменений и корректировке конфигурации сложных ПС и документов. Он взаимодействуют с заказчиком и пользователями, определяющими разработку или эксплуатацию ПС, для согласования изменений в системе, в контракте и в техническом задании. Заказчик системы должен оценивать и утверждать наиболее крупные изменения, заметно влияющие на условия контракта, технические требования или стоимость проекта ПС.
Организационная структура коллектива специалистов при корректировках сложных комплексов программ должна учитывать:
•	цели и функции управления конфигурацией;
•	взаимодействующие организации;
•	службы проектирования, закупок и контрактов;
•	систему обеспечения качества и другие средства, которые могут быть привечены, охватывая, если необходимо, субподрядчиков и поставщиков.
Она должна определять связи между различными видами деятельности, непосредственно входящими в процесс управления конфигурацией, обеспечивать координацию действий с другими работами, а также распределение соответствующих полномочий и ответов за все действия по управлению корректировками документов. При организации сложного проекта следует идентифицировать инстанцию, уполномоченную утверждать конфигурационные базы программных продуктов и документов для поставки заказчику и пользователям, и любые изменения к ним.
В процессе эксплуатации версий ПС у каждого пользователя могут появляться некоторые претензии к функционированию, которые квалифицируются им как ошибки или дефекты эталонной или собственной версии. Для общения с пользователями и накопления информации о выявляемых недостатках в широко тиражируемых сложных ПС целесообразно выделение группы специалистов высокой квалификации, овладевших всеми функциональными возможностями данного ПС. От пользователей или заказчика могут поступать также предложения по внесению изменений в версию для улучшения эксплуатационных характеристик и расширения функциональных возможностей ПС. Ана
2.4, УПРАВЛЕНИЕ ДОКУМЕНТИРОВАНИЕМ ЖЦ ПС
107
логичные предложения могут поступать от разработчиков комплекса программ. Для оценки предложений полезно экспериментальное тестирование предварительных вариантов изменений версии ПС и документов.
Структура коллектива разработчиков, обычно, в значительной степени отражает структуру разрабатываемого ПС. Особенно это заметно при создании крупных комплексов программ размером 105 —106 строк [1]. При этом группы функциональных программ локализуются по соответствующим группам специалистов с целью минимизации связей и упрощения взаимодействия, как между группами разработчиков, так и между создаваемыми ими программами и документами.
Для реализации мероприятий по планированию и управлению жизненным циклом и документированием концептуально целостных, крупномасштабных ПС и обеспечения их качества в пределах допустимых затрат, необходимы организационные действия менеджеров и системных архитекторов, направленные на подбор и обучение коллектива специалистов разных категорий и специализаций. Перечисленные выше специализации и квалификации персонала, участвующего в крупномасштабных проектах ПС, требуют соответствующей их подготовки, отбора и обучения. Должны быть разработаны и документированы планы проекта, требования и цели обучения, а также разработаны руководства, включая документы, используемые для обучения (см. шестую часть ISO 15504). Персонал, ответственный за выполнение конкретных действий с высоким риском [1] должен быть аттестован, если это необходимо, на основе соответствующего образования, подготовки и/или опыта работы.
Оценка размера будущего продукта и комплекса документации является весьма важной, поскольку она является частью одной наиболее сложной задач проекта: установки реальных ориентиров затрат для заказчика. Нереальные ожидания, основанные на неточных оценках требуемых ресурсов, представляют собой одну из частых причин провала проектов вследствие высоких рисков ограничения ресурсов. Зачастую провала причина заключается не в недостаточной производительности команды специалистов проекта, а в неточном предвидении уровня ее уровня, и размера документации проекта. Так как величина и достоверность определения размера проекта ПС ключевой фактор последующего анализа влияния ограничений ресурсов, то целесообразно применять несколько доступных методов для его оценивания.
108
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Конкретизация функций, структуры ПС, состава компонентов проекта позволяет более достоверно определить размеры групп программ и, суммируя их, рассчитать размер всего комплекса программ и документов. Кроме того, на этом этапе повышается возможность выбора и использования аналогов данного проекта, так как становятся более определенными задачи, функции и компоненты разрабатываемого ПС, для которого желательно найти аналоги с известными апробированными характеристиками. Особенно сильно на снижение суммарных затрат влияет использование готовых компонентов и документов из предшествующих разработок. При анализе аналогов могут быть выделены компоненты, пригодные для повторного применения в новом проекте. Это позволяет оценить возможную долю использования готовых компонентов и тем самым определить эффективный размер комплекса программ и документов, подлежащий непосредственной разработке.
2.5. Документация управления качеством программного средства
Все можно сделать лучше, чем делалось до сих пор.
(Генри Форд)
Состав и содержание документации системы качества предприятия зависят от характеристик проектирования, разработки и модификации программных средств, а также от требований к их качеству и особенностей технологической среды. Поэтому необходимый комплект документов для каждого предприятия или проекта следует выбирать и адаптировать применительно к этим характеристикам [2].
Оцениваемыми при сертификации показателями системы качества являются наличие соответствующих документов и практическое выполнение требований международных стандартов серии ISO 9000 и должностных инструкций специалистами предприятия-разработчика. Клиент-заявитель должен подготовить и предъявить проверяющей испытательной лаборатории согласованный между заказчиком и разработчиком и утвержденный комплект документов для проверки их до
2.5. ДОКУМЕНТАЦИЯ УПРАВЛЕНИЯ КАЧЕСТВОМ ПС
109
стоверности, достаточности состава и качества изготовления в соответствии с нормативными документами.
Примерный комплект основных документов состоит из трех групп й:
•	базовые нормативные документы системы качества в соответствии с номенклатурой и содержанием серии стандартов ISO 9000, а также подготовленные разработчиками на их основе программа, руководство и инструкции, предъявляемые испытателям (сертификаторам) системы качества;
•	исходные документы, характеризующие конкретное предприятие или проект и жизненный цикл программного средства, подготавливаемые руководством предприятия или проекта для сертификации системы качества;
•	отчетные документы испытателей, отражающие результаты проверки (сертификации) системы качества предприятия, представляемые органу сертификации, заявителю и руководству проверяемого предприятия.
Перечень и приблизительное содержание групп этих документов ориентированы на общий случай проверки систем качества предприятий, поддерживающих жизненный цикл крупномасштабных ПС, базирующихся на международных стандартах. Комплект документов может сокращаться и адаптироваться по согласованию между заявителем, испытателем и руководством проверяемого предприятия в соответствии с характеристиками проектов программных средств.
Некоторые документы могут объединяться в интегрированные отчеты с четкой ответственностью определенных специалистов за их выполнение.
Основные базовые нормативные документы перечислены в [2]. Для непосредственного применения в системе качества должны быть разработаны и использованы на предприятии следующие документы.
1.	Значения показателей качества ПС, выделенные и конкретизированные на основе стандарта ISO 9126.
2.	Адаптированная версия или перечень разделов и рекомендаций стандарта ISO 12207, выделенных при адаптации и обязательных для применения в системе качества конкретного предприятия или проекта.
110
2, ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
3.	Адаптированная версия или перечень разделов и рекомендаций стандарта ISO 9000-3, выделенных при адаптации и обязательных для применения в системе качества предприятия.
4.	Адаптированная версия и утвержденная редакция «Руководства по качеству» предприятия на основе рекомендаций стандарта ISO 10013.
5.	Адаптированная версия и утвержденная редакция «Программы качества» предприятия на основе рекомендаций стандарта ISO 10005.
6.	Адаптированная версия и утвержденная редакция «Руководства по конфигурационному управлению» на основе рекомендаций стандарта ISO 10007.
В число документов системы качества предприятия, обеспечивающего жизненный цикл программных средств, входят [2]:
• исходные документы характеристик жизненного цикла ПС:
—	требования к показателям и системе качества ПС;
—	характеристики и этапы жизненного цикла проекта ПС;
—	комплект эксплуатационных документов ПС;
—	документация, методы и средства автоматизации жизненного цикла ПС;
—	планы проверок и испытаний применения процедур системы качества;
—	методики сопровождения и управления конфигурацией ПС;
• результирующие документы проверок сертификации системы качества предприятия:
—	адаптированный, актуальный комплект документов системы качества предприятия;
—	результаты испытаний состояния и применения документов системы качества предприятия;
—	оценки достаточности тестов для сертификациолнных испытаний системы качества;
—	результаты испытаний достигнутого качества ПС;
—	протоколы и акт проверок системы качества на соответствие требованиям сертификации;
—	сертификат системы качества предприятия для обеспечения жизненного цикла программных средств.
2.5. ДОКУМЕНТАЦИЯ УПРАВЛЕНИЯ КАЧЕСТВОМ ПС
111
Исходные документы отражают особенности жизненного цикла программного средства. В них приводится описание целей, требований и обязательств предприятия-разработчика в области системы качества, критериев качества процесса разработки, поставки и поддержки всего жизненного цикла ПС.
Там же описываются характеристики программных средств, создаваемых на предприятии, и внешней среды их жизненного цикла. Все это необходимо для адаптации и подготовки рабочих версий стандартов системы качества предприятия в соответствии с рекомендациями Приложений А и В стандарта ISO 12207, а также рекомендациями стандартов ISO 9000-3 и ISO 9126.
Предоставляется комплект эксплуатационных документов, поставляемых заказчику и пользователям для обеспечения ЖЦ конкретной версии ПС.
В комплект входит документация и средства автоматизации проектирования, разработки, модификации, контроля и испытаний, используемых для обеспечения жизненного цикла ПС, планы и методики проведения проверок и испытаний применения и оценки, эффективности процедур системы качества предприятия, методика сопровождения, идентификации компонентов ПС и документации, анализа и утверждения модификаций.
Наконец, в состав исходных документов входит методика конфигурационного управления, утверждения, хранения, защиты, копирования версий ПС и сопровождающих документов, а также накопления и хранения зарегистрированных в архиве предприятия данных о показателях качества ПС в течении жизненного цикла.
Результирующие документы проверок являются сертификациями системы качества предприятия. В их состав входят [2]:
•	отчет о наличии, актуальности и систематичности оформления документации, адаптированной к требованиям и положениям системы качества предприятия, обеспечивающей интегрированный процесс гарантии качества на протяжении всего жизненного цикла ПС;
•	результаты контроля и испытаний состояния и применения системы качества, проводимых периодически для определения ее пригодности и эффективности;
•	отчет о наличии и поддержании в рабочем состоянии методик проведения проверок и документально оформленных отчетов о
112
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
результатах анализа достигнутого качества выполнения контракта;
•	результаты реализации плана разработки, документально оформленных входных и выходных данных для каждого этапа разработки и протоколов проверки выходных данных всех этапов жизненного цикла ПС;
•	результаты практического выполнения «Программы качества* и осуществления регламентированной деятельности в области качества на всех этапах жизненного цикла ПС;
•	результаты аттестации имитаторов внешней среды и генераторов текстов, а также оценка их достаточности для выполнения сертификационных испытаний ПС;
•	результаты регистрации данных о достигнутом качестве комплекса программ: процедуры идентификации, накопления, хранения и изъятия зарегистрированных данных о показателях качества ПС и его компонентов;
•	результаты анализа выполнения планов и методик проведения испытаний, протоколы испытаний, оценки соответствия результатов испытаний предъявляемым требованиям, результаты испытаний, утвержденные представителями заявителя, заказчика и поставщика;
•	акт о результатах проверок системы качества предприятия и выводы о соответствии требованиям к сертификации;
•	сертификат системы качества предприятия и обеспечения жизненного цикла программных средств.
2.6. Структура и содержание документов по этапам жизненного цикла программного средства
Любая структура становится архитектурой, а не скульптурой, тогда когда ее элементы больше не оправдаются культурой.
(Гийом Аполлинер)
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
113
В соответствии с [1] выделяют следующие типы документов, создаваемых в процессе жизненного цикла ПС.
1.	Документы предварительных требований, спецификаций и ресурсов для разработки программного средства
2.	Документы процессов проектирования и выбора характеристик качества программного средства
3.	Документы процессов разработки и программирования компонентов программных средств
4.	Документы верификации и тестирования компонентов программных средств
5.	Документы квалификационного тестирования, испытаний и оценивания качества программных средств
6.	Документы сопровождения и конфигурационного управления версиями программного средства
7.	Документы процессов эксплуатации программных средств.
Приведем примерное содержание этих документов, описанное в виде содержания в книге [1].
2.6.1. Документы предварительных требований, спецификаций и ресурсов для разработки программного средства
1.	В процессе интервью заказчиков и пользователей о проблемах и целях создания программного продукта определяется профиль заказчика или пользователя, оцениваются проблемы создания или модификации программного средства. В это же время определяется пользовательская среда:
•	имеют ли пользователи опыт работы с данным типом программных средств;
•	какая вычислительная платформа используется;
•	каковы ожидания заказчика относительно практичности продукта;
•	в каком виде должна быть представлена справочная информация для пользователя (в интерактивном или в виде печатной копии).
Следует зафиксировать предложения аналитика-разработчика относительно проблемы заказчика и выполнить оценку предлагаемого аналитиком метода решения проблемы, оценку возможностей, а так
114
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
же произвести оценку необходимого уровня надежности и производительности и потребностей в сопровождении программного продукта.
В результате оформляется заключение аналитика о потребностях или проблемах, с наивысшими приоритетами, выявленных в беседе с заказчиком (пользователем).
2.	Результаты обследования и описание системы и целей разработки комплекса программ содержат характеристики существующей системы информатизации или управления, описание существующей системы и ее недостатков, обоснование необходимости совершенствования системы. Здесь же приводятся производственнохозяйственные, научно-технические и экономические цели, критерии и ограничения создания нового ПС, критерии оценки эффективности создания и ограничения ресурсов при создании нового ПС. В данном документе перечисляются функции и задачи создаваемого, нового ПС с обоснованием выбора перечня автоматизируемых функций и комплексов задач, указанием возможной очередности внедрения функциональных задач и требования к характеристикам реализации функций. В обязательном порядке отмечаются ожидаемые техникоэкономические результаты создания ПС, приводится перечень основных источников экономической эффективности, получаемых в результате создания продукта. Производится оценка ожидаемых изменений основных технико-экономических и социальных показателей функционирования системы и ожидаемых затрат на создание и эксплуатацию ПС с распределением их по очередям создания системы и по годам и ожидаемые обобщающие показатели экономической эффективности системы с новым ПС.
Наконец, делаются выводы и приводятся предложения о производственно-хозяйственной необходимости и техникоэкономической целесообразности создания нового ПС и совершенствовании организации и технологии процесса деятельности системы и ПС. Даются обобщенные рекомендации по созданию нового или модернизированного ПС.
3.	Технико-экономическое обоснование проекта программного средства состоит из указания базовых стандартов, методов, правил и инструментальных средств, которые могут быть использованы при разработке требований к программному продукту, а также стандартов и методов, которые должны быть применены при разработке требований к структуре и компонентам ПС, системы основных обо
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
115
значений, которые следует применять для описания требований, диаграмм потока данных и формальные языки спецификаций. Здесь приводятся общие исходные данные и осуществляется выбор методики и сценария первичной оценки требований технико-экономических характеристик ПС. Производятся предварительные расчеты трудоемкости и стоимости разработки ПС, длительности разработки ПС, необходимого числа специалистов. На основе созданных документов проводится оценка влияния технико-экономических факторов на качество проекта ПС, а также предварительная оценка результирующих техникоэкономических характеристик проекта ПС. Таким образом, выполняются следующие расчеты:
•	расчет уточненной трудоемкости и стоимости разработки проекта программного продукта;
•	расчет уточненной длительности разработки проекта ПС;
•	уточненный расчет необходимого числа специалистов для разработки проекта ПС;
•	расчет уточненного распределения трудоемкости, длительности, числа специалистов по этапам работ.
На основе полученных данных осуществляется обобщение основных технико-экономических характеристик и полной стоимости разработки проекта ПС и проводится анализ результатов и техникоэкономическое обоснование целесообразности продолжения проектирования программного продукта.
4.	Концепция и основные предложения по созданию базовой версии программного средства. В данном документе описываются обобщенные результаты обследования и изучения существующей системы и внешней среды, перечисляются базовые стандарты проекта программного продукта и описываются потребности потенциальных пользователей ПС. В документе приводится список характеристик комплекса задач, входные и выходные данные.
На их основе описываются и оцениваются преимущества и недостатки разработанных альтернативных вариантов функций в концепции создания ПС, проводится сопоставительный анализ требований пользователя к ПС и вариантов функций в концепции ПС по удовлетворению требований заказчика и пользователей.
Таким образом, обосновывается выбор оптимального варианта содержания и приоритетов комплекса функций в концепции, на основе чего имеем общее описание постановки выбранных задач и функций
116
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
нового ПС и происходит конструирование предполагаемой структуры, состава компонентов и интерфейсов с внешней средой.
В данном документе обязательно должны быть отмечены ожидаемые результаты и возможная эффективность реализации выбранного варианта концепции ПС, приведен ориентировочный план реализации выбранного варианта концепции ПС и указаны требования к составу и содержанию документации проекта ПС. Тут повторно приводится оценка необходимых затрат ресурсов на разработку, ввод в действие и обеспечение функционирования нового ПС и предварительный состав требований, гарантирующих качество ПС, а также предварительные условия испытаний и приемки системы.
5.	Предварительный укрупненный план проектирования и разработки базовой версии программного средства представляет собой документ, в котором отмечено общее назначение и сфера действия плана, разработаны перечень и план-график взаимосвязи этапов и работ. Причем, для каждой работы, выделенной в соответствии со стандартом жизненного цикла ПС, и включенной в план приводится следующая информация:
•	наименование работы;
•	контролируемые характеристики объекта разработки;
•	контролируемые показатели процесса выполнения плана;
•	требования к результатам и качеству;
•	состав отчетной документации о результатах выполнения плана и достигнутых показателях качества;
•	дата начала и окончания работы;
•	наименование специалистов и подразделений-участников работы;
•	фамилия и должность ответственного исполнителя этапа работ.
Таким образом, в документе определяются оценка возможности, этапы и сроки реализации конкретных требований концепции и решения функциональных задач.
6.	Системный проект, общее описание программного средства и среды разработки для согласования между заказчиком и разработчиком (п. 3-5). В документе содержатся основные сведения о техническом, информационном и других видах внешней среды, необходимые для разработки программного средства; ссылки на документы проекта системы, влияющие на разработку конкретного программного средства. Здесь определяется структура программного средства (перечень
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
117
функциональных частей и компонентов с указанием их взаимосвязей и обоснованием выделения каждой из них), функции частей программного средства (назначение и описание основных проблем и функций для каждой части и компонента ПС). Здесь фиксируется содержание решаемой проблемы. В качестве дополнительных документов прикладывается соглашение с заказчиком по определению проблемы, приводится список заинтересованных лиц и пользователей, а также ограничения, которые необходимо наложить на решения.
В отличие от предыдущих документов, здесь подробнее описывается содержание потребностей заказчика и пользователей, категории критичности системы и программного средства. Принято выделять три уровня критичности [2].
Критическое ПС - для него проявление дефекта при испытаниях или возникновение отказовой ситуации прекращает безопасное функционирование системы обработки информации и резко увеличивает риск для жизни и здоровья людей или риск аварии оборудования с большим ущербом.
Важное ПС - для него проявление дефекта или возникновение отказовой ситуации может существенно снизить качество выпускаемой продукции и заметно увеличить риск и цену грубых ошибок при обработке информации.
Ординарное ПС - для него ошибки или отказовые ситуации отражаются только на качестве и надежности выходных результатов и не могут привести к значительному ущербу в объектах внешней среды или к потерям у пользователей.
Далее производится определение системы и программного продукта, управление и согласование масштаба проекта и контроль изменений, который включает в себя:
•	соглашение с заказчиком относительно масштаба проекта и решений по изменению масштаба;
•	фиксацию новых функций, возникающих в результате нормального течения проекта, контроль за изменениями и решениями;
•	систему управления запросами изменений, чтобы гарантировать, что они поступают через контроль за изменениями.
Выполняется построение корректной системы и комплекса программ, а именно:
118
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	анализ и оценка рисков для определения плана действий по верификации и проверке корректности требований, на основе результатов этих оценок;
•	тестовые процедуры и примеры, которые трассируются к прецедентам, а также к функциональным и конструктивным требованиям;
•	периодическое проведение приемочных испытаний компонентов, чтобы проверять правильность частных результатов работы и обеспечить постоянное участие заказчиков.
При этом осуществляется непрерывное управление процессом работы с требованиями.
7. Техническое задание на предварительное (детальное) проектирование программного средства состоит из следующих необходимых частей:
• общие сведения:
—	титульный лист с утверждающими и согласующими подписями;
-	полное наименование проекта ПС;
—	назначение и цель разработки (развития) ПС;
—	основание для выполнения и финансирования проекта ПС;
-	организация - заказчик проекта;
—	организация - головной исполнитель и соисполнители проекта;
—	общие сроки выполнения проекта;
•	общие технические требования, стандарты и базовые нормативные документы для выполнения проекта ПС;
•	характеристики системы информатизации или управления;
—	общие требования к системе и внешней среде;
—	общие требования от системы к структуре программного средства:
—	требования к программному средству в целом;
—	требования к функциям и основным задачам проекта ПС;
—	требования к внешней среде проекта ПС;
—	требования к классам и характеристикам пользователей;
• детальные спецификации требований к функциям, компонентам и эксплуатационным характеристикам ПС:
—	требования к структуре и функционированию ПС;
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
119
—	требования к надежности и безопасности применения;
—	требования к защите информации;
—	требования к стандартизации и унификации;
—	требования к интерфейсам между компонентами, с внешней средой и с пользователями;
•	специальные требования к аппаратной и операционной платформам для реализации ПС;
•	требования к содержанию, оформлению и обозначениям эксплуатационной и технологической документации;
•	требования к составу и содержанию работ по внедрению ПС в эксплуатацию;
•	этапы, сроки и график выполнения основных работ;
•	ожидаемые результаты применения ПС и форма их представления;
•	порядок контроля, испытаний и приемки результатов проекта;
•	предложения по применению и развитию проекта ПС.
2,6.2. Документы процессов проектирования и выбора характеристик качества программного средства
1. Стандарты, и ограничения на процессы проектирования программного средства: указываются стандарты, методы, правила и описания инструментальных средств, которые следует применять при разработке архитектуры ПС и требований компонентов нижнего уровня; стандарты и общие методы описания проекта ПС, которые будут использованы; соглашения по идентификации компонентов, версий и продуктов проекта программного средства; ограничения, налагаемые на применяемые методы проектирования; ограничения на использования инструментальных средств автоматизации проектирования; ограничения на проектирование структуры программ - запреты на использование рекурсий, динамических объектов, альтернативных имен, сокращенных выражений; ограничения по сложности максимального уровня вложенности циклов, последовательных вызовов и условных структур, использования безусловных переходов, число входных/выходных точек компонентов и модулей программы.
120
2, ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2. Спецификация требований к системе и к комплексу программ состоит из:
•	требований проекта системы комплекса программ как целого и общей архитектуры системы;
•	требований к унификации проекта интерфейсов и базы данных;
•	требований и обоснование выбора проектных решений уровня системы, выбора компонентов системы, описания поведения системы с точки зрения пользователя;
•	спецификаций требований верхнего уровня, производные требования к компонентам ПС и требования к интерфейсам между системными компонентами, элементами конфигурации ПС и аппаратуры;
•	описания распределения системных требований по компонентам ПС с учетом требований, которые обеспечивают характеристики качества;
•	требований к архитектуре системы, содержащей идентификацию и функции компонентов системы, их назначение, статус разработки, аппаратные и программные ресурсы;
•	требований концепции совместного целостного функционирования компонентов ПС, описание их динамических связей;
•	требований стабильности интерфейсов между аппаратными и программными компонентами и пользователими;
•	требований возможности анализа трассируемости компонентов программного средства системы к системным требованиям проекта;
•	требований для системы или/и подсистем и методов, которые должны быть использованы для гарантии того, что каждое требование будет выполнено.
3.	Предварительное описание и контроль согласованности требований компонентов проекта программного средства включает в себя в первую очередь описание архитектуры и контроль согласованности требований компонентов нижнего уровня ПС, которые должны удовлетворять требованиям верхнего уровня к комплексу программ. Здесь же приводится детализированное описание того, как компоненты ПС удовлетворяет специфицированным требованиям верхнего уровня к ПС, включая алгоритмы, структуры данных, и описание распределения требований по процессорам и задачам для реализации.
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
121
Архитектура комплекса программ в составе системы определяет структуру компонентов ПС, предназначенного для реализации заданных требований на систему. Далее проводится описание вход-ных/выходных данных для внутренних и внешних интерфейсов архитектуры системы и комплекса программ, анализ корректности описаний потоков данных и потоков управления.
Перечисляются ограничения на использование ресурсов. Приводится стратегия для управления каждым ресурсом. Определяются границы рабочего диапазона и методы измерения времени выполнения и использования памяти при функционировании ПС. Обосновываются те решения проекта, которые относятся к перечисленным требованиям, связанным с применением системы и ПС.
4.	Описание функционирования программного средства, взаимодействия с объектами внешней среды и человеко-машинного диалога подразумевает указание перечня исходных материалов и документов, использованных при разработке функциональной части проекта ПС; особенностей системы, влияющих на проектные решения и компоненты ПС по автоматизированным функциям; данных о системах, взаимосвязанных с разрабатываемым ПС; сведений об информации, которой ПС должно обмениваться с абонентами и другими системами. Таким образом, в этом документе приводится описание информационной модели системы, в которой указываются цели комплекса программ и автоматизируемые функции и характеристика функциональной структуры, типовые решения с указанием функций и задач, для выполнения которых они применены. Особенно подробно описывается функциональная пригодность документируемого ПС, а именно:
•	соответствие структурных характеристик комплекса программ назначению и функциям ПС;
•	соответствие назначения целям применения ПС;
•	соответствие требований к заданным функциям назначению ПС;
•	соответствие исходной информации требованиям к функциям ПС;
•	соответствие состава и содержания выходной информации для потребителей назначению и функциям ПС.
5.	Описание алгоритмов компонентов (модулей) программного средства выполняется в следующем порядке. После постановки задачи, для решения которой используется текущий компонент, приво
122
2, ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
дятся краткие сведения о процессе (объекте), при управлении которым используется алгоритм; определяются воздействия на процесс пользователями, осуществляемые при функционировании алгоритма. Обязательно указываются ограничения на возможность и условия применения алгоритма; требуемые характеристики качества решения; а также состав и общие требования к входным и выходным данным.
Далее перечисляются массивы информации, сформированные из входных сообщений системы и массивы информации, полученные в результате работы других алгоритмов и сохраняемые при реализации данного алгоритма. К результатам решения следует отнести перечень и содержание массивов информации, формируемых в результате реализации алгоритма.
Документ содержит и описание математической модели или экономико-математического описания процесса (объекта); перечень принятых допущений и оценки степени соответствия принятой модели реальному процессу (объекту). Сюда же относятся сведения о результатах научно-исследовательских работ, если они использованы для разработки алгоритма; описание логики функционирования алгоритма и способа формирования результатов решения; а также последовательности этапов счета, расчетные и логические формулы, используемые в алгоритме.
Требования к разработке программы для реализации алгоритма включают в себя:
•	диагностические сообщения при работе с программой;
•	требования к контролю данных в процессе выполнения операций алгоритма;
•	ограничения, связанные с машинной реализацией программы алгоритма;
•	требования к контрольной задаче алгоритма.
6.	Описание информационного обеспечения программного средства и системы управления базами данных состоит из перечня информационного обеспечения комплекса программ; перечисления и назначения всех баз и наборов данных. Перечисляются все проектные решения, связанные с применением базы данных с точки зрения пользователя. Описываются интерфейсы базы данных с другими системами, элементами конфигурации ПС и аппаратуры и способы доступа к базам данных, время реакция баз данных на входные запросы и другие эксплуатационные характеристики.
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
123
Детально описываются алгоритмы работы с базами данных и возможные ограничения; организация интерфейсов и информационного обеспечения программного средства для сбора и передачи информации. Приводится система классификации и кодирования информации в комплексе программ, организация информации баз данных и организация ведения и изменения каждой информационной базы.
7.	Требования к характеристикам качества проекта программного средства включает перечисленные ниже требования:
•	к корректности программного средства;
•	к способности и качеству взаимодействия компонентов системы и ПС;
•	к защищенности - безопасности ПС;
•	к характеристикам надежности функционирования ИС;
•	к эффективности функционирования ПС;
•	к практичности применения ПС;
•	к сопровождаемости ПС;
•	к мобильности ПС.
8.	Пояснительная записка к предварительному или детальному проекту программного средства кроме наименования и общих сведений о проектируемой системе и наименовании и номерах документов, их номера и дату утверждения, на основании которых ведется проектирование ПС, содержит и описание процесса функционирования и применения ПС, перечень основных технических решений, информацию об организации баз данных компонентов и процессов проектирования версий программного средства, логической и физической структуре баз данных проектирования компонентов и ПС в целом.
Перечисляются мероприятия по подготовке системы и ПС к вводу в действие и к эксплуатации.
9.	Описание концепции технологии автоматизированного проектирования программного средства подразумевает постановку задач и цели автоматизации проектирования ПС. Данный документ включает в себя методику проектирования ПС, описание инструментальных средств для создания ПС, описания проектных процедур в жизненном цикле ПС и определение оценки качества результатов проектирования.
10.	План и поддерживающее его «Руководство по документированию проекта жизненного цикла программного средства» состоит из следующих документов:
124
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	общая структура комплекта документов;
•	перечень исходных стандартов и нормативных документов;
•	номенклатура и структура содержания каждого документа;
•	требования к качеству, оформлению и обозначению исходных и результирующих документов;
•	оценка соответствия стандартам установленного комплекта документов;
•	регламент комплектования и хранения документов;
•	правила обращения, изменения и сопровождения документов;
•	план и графики подготовки, проверки, редактирования, согласования, утверждения и распространения документов для каждого этапа жизненного цикла:
•	обязанности и ответственность специалистов за содержание и качество конкретных документов;
•	необходимые и используемые ресурсы, обеспечивающие создание конкретных документов требуемого качества.
11.	Ведомость предварительного или детального проекта программного средства (п. 7—10):
•	согласованный перечень документов предварительного (детального) проекта программного средства, предъявляемых заказчику на бумаге и/или в машинных файлах;
•	оценка соответствия комплекта, содержания и качества документов проекта требованиям спецификаций, технического задания и/или контракта (договора) на проектирование по разделам проекта программного средства.
2.6.3. Документы процессов разработки и программирования компонентов программных средств
1.	План разработки компонентов программного средства состоит из описания целей, стандартов и модели жизненного цикла, которые должны быть использованы в процессах разработки компонентов ПС. В этом плане производится идентификация стандартов на разработку компонентов ПС. Здесь же описываются процессы ЖЦ ПС, которые должны быть использованы для формирования конкретного жизненного цикла компонента данного проекта, включая критерии перехода между процессами и компонентами ПС.
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
125
Обоснование выбора используемой среды разработки ПС в аппаг ратной и программной части, включает выбор:
•	методов и средств разработки требований к компонентам ПС;
•	методов и средств проектирования компонентов ПС;
•	языков программирования компонентов ПС;
•	средств кодирования, компиляторов, редакторов связей и загрузчиков.
Приводится аппаратная поддержка для инструментальных средств программирования компонентов ПС и составляется план-график разработке компонентов ПС по этапам проекта.
2.	План обеспечения качества компонентов программного средства включает в себя описание методов, которые должны быть использованы для того, чтобы достичь требуемое качество компонента ПС; среды обеспечения качества, включая область действия, организационную ответственность, интерфейсы, стандарты, процедуры, инструментальные средства и методы. В этом плане утверждаются полномочия службы обеспечения качества, ее ответственности и независимости, включая полномочия специалистов на утверждение версий программных средств и компонентов. Приводится перечень и план-график работ обеспечения качества, которые должны быть выполнены для каждого процесса жизненного цикла компонента ПС и на протяжении всего жизненного цикла. Производится синхронизация работ процесса обеспечения качества компонентов, относительно работ других процессов жизненного цикла ПС и определение отчетов, которые будут подготовлены в процессах обеспечения качества компонентов ПС.
в. Стандарты кодирования компонентов программного средства описывают методы, правила и инструментальные средства, которые будут использованы для кодирования компонентов ПС. Они включают в себя перечень языков программирования и/или какое-либо их подмножество. Сюда же входят стандарты представления, комментирования, оформления и документирования исходного кода, истории изменений, входные и выходные данные, а также наиболее значимые глобальные данные, а также соглашения по наименованию для компонентов, подпрограмм, переменных, констант, версий.
4.	Руководство по программированию компонентов проекта комплекса программ включает в себя описание среды программирования: конфигурации и перечня компонентов системы, рабо
126
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
чих характеристик, возможностей и ограничения, включая машинный цикл и пр. В данном руководстве указывается информация о всех возможностях применения языка программирования.
5.	Документация на разработанный функциональный программный компонент или модуль программного средства (п. 2 4) включает в себя:
•	идентификатор, техническое задание и/или спецификация требований на разработку компонента; включая, имя автора и дату создания версии компонента;
•	текст компонента ИС, написанный на исходном языке программирования, и команды компилятора, генерирующие объектный код из исходного текста, информация для редактирования связей и загрузки, а также текст комментариев;
•	код, который является непосредственно пригодным для использования процессором объектного компьютера и загружаемый в аппаратные средства или вычислительную систему;
•	описание программы в виде печатного документа и/или машинных файлов;
•	фрагмент руководства пользователя - описание применения программного компонента (при необходимости);
•	исходный текст программы на языке программирования в виде печатного документа и/или машинных файлов с комментариями;
•	исходный текст и исполняемый объектный код программы на машинных носителях.
2.6.4. Документы верификации и тестирования компонентов программных средств
1.	Базовые документы, регламентирующие верификацию и тестирование программных компонентов состоят из:
•	руководства программистам по применению методологии, средств автоматизации и стандартов программирования при разработке компонентов ПС;
•	руководства программистам по управлению качеством компонентов и комплекса программ;
•	плана обеспечения процессов верификации и тестирования средствами генерации тестов и обработки результатов функционирования компонентов ПС;
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
127
•	исходных текстов запрограммированных и оформленных компонентов и описаний данных;
•	общего плана организации и порядка тестирования компонентов;
•	описания оформления типовых тестов, генераторов тестовых данных и сценариев, используемых при тестировании компонентов;
•	типовых форм (шаблонов) отчетов о результатах верификации и тестирования, достигнутых показателях качества, откорректированных программистами после завершения разработки компонентов;
•	образцов текстов компонентов на языке программирования после завершения верификации тестирования.
2.	Исходные данные для верификации программных компонентов включают в себя требования к функциональности, эффективности и к качеству системы, детализированные в исходных требованиях высокого уровня к ПС, производные требования к компонентам и обоснование их необходимости. Каждое требование высокого уровня к ПС трассировано точными, однозначными и достаточно детализированными требованиями к компонентам, и эти требования не конфликтуют друг с другом. Отсутствуют неоднозначности и конфликты между требованиями к компонентам и к возможностями аппаратных и программных средств объектного вычислителя, особенно такими, как время реакции системы и характеристики аппаратуры ввода/вывода. Оформление требований к ПС и компонентам полностью соответствует стандартам на создание спецификаций требований. Любые отклонения от стандартов обоснованы. Функциональные и конструктивные характеристики качества компонентов, предназначенные для реализации, полностью отражены и адекватны требованиям высокого уровня к ПС.
3.	Результаты верификации корректности взаимодействия компонентов в составе программного средства означают удостоверение внутренней непротиворечивости и полноты реализации компонентами требований к программному средству, посредством последовательного прослеживания выполнения комбинации из просмотров, анализов, разработки тестовых сценариев и процедур.
Требования к системе, предназначенные для программной реализации, корректно переработаны в спецификацию требований высокого уровня к комплексу программ, удовлетворяют исходным систем-
128
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
ным требованиям. Требования высокого уровня правильно переработаны в архитектуру ПС и в спецификации требований к функциональным компонентам низкого уровня, которые удовлетворяют требованиям высокого уровня. Выработаны спецификации требований к функциональным компонентам ПС, расположенным между компонентами высокого и низкого уровня, каждый раз удовлетворяют требованиям более высокого уровня. Архитектура ПС и спецификации требований к компонентам низкого уровня корректно переработана. Исполняемый объектный код удовлетворяет требованиям к исходному тексту программных компонентов.
•	Утверждается организационная ответственность внутри процесса верификации компонентов ПС и интерфейсы с другими процессами жизненного цикла.
•	Формализуются методы, которые будут использованы на каждом этапе процесса верификации ПС. В частности, это методы просмотра и трассирования спецификаций требований по уровням детализации описаний компонентов и методы проверки трасси-руемости и оценки полноты покрытия верификацией компонентов ПС.
•	Утверждаются методики и процедуры выполнения просмотров и анализа, детализация верификации компонентов ПС в части области цействия, глубины методов просмотров и анализа.
4.	Перечислим исходные данные для тестирования компонентов:
•	документация на разрабатываемый программный компонент:
•	выбранные методы верификации и тестирования компонентов:
•	правила построения и описания тестов компонентов на разных уровнях их представления;
•	правила структурного построения и интерфейсов компонентов между собой, а также с внешней средой и с пользователями;
•	эталонные значения и/или распределения исходных и результирующих данных, отражающие требующиеся функции, сценарии тестирования и покрытие тестами компонента во всем заданном разнообразии его поведения;
•	тестовые сценарии исходных и результирующих данных, явля-ющиеся достаточно представительной выборкой из полной совокупности значений и распределений эталонных данных, ограниченной доступными ресурсами на тестирование компонента;
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
129
•	доступные ресурсы на тестирование компонента;
•	критерии качества тестирования и требуемая полнота покрытия тестами компонентов, в которые входят описания реализуемых функций и характеристики качества реализации функций;
•	допуски на отклонение результатов функционирования программ и показателей качества компонентов от требуемых эталонных значений и распределений, в пределах которых считается, что компонент удовлетворяет предъявленным требованиям к качеству.
5.	Организация, подготовка тестирования и обеспечение качества компонентов включает в себя системные и функциональные требования к конкретному компоненту, ранжированные требуемые показатели качества к каждому компоненту. В этих документах описывается декомпозиция обобщенных показателей качества ПС и компонентов по контролируемым этапам разработки и разделы по качеству в спецификациях требований на модули и компоненты, а также на их связь с методами и этапами тестирования. Приводятся методы, технология и средства автоматизации разработки и тестирования, обеспечивающие создание каждого компонента с заданными показателями качества, методы и средства объективного измерения требуемого покрытия тестами и достигнутого качества каждого компонента на фиксированных этапах его разработки. Указываются и включаются документы и методики для обеспечения и контроля соблюдения правил и технологии проектирования, тестирования и обеспечения всего жизненного цикла компонентов и программного средства. Приводится структура и содержание (шаблон) каждого документа отражающего результаты этапа тестирования компонента, качество выполненных работ и полноты покрытия тестами.
6.	Сценарии тестирования и спецификации тестов для каждого компонента начинаются с описания методов и вида тестирования адекватных компоненту, а также основной цели его выполнения. Приводится план тестирования в соответствии с выбранным методом с учетом ограниченных ресурсов испытаний, имеющихся для достижения заданной достоверности проверки качества компонента. Рассматривается спецификация общей схемы сценариев тестирования компонента, которая состоит из:
130
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	характеристики компонента, требуемая полнота покрытия тестами для их контроля, охватываемые этой схемой и соответствующими ей тестами;
•	специфических критериев для характеристик программного продукта, позволяющие оценивать компонент: годен - не годен.
Описываются контрольные сценарии тестирования - набор конкретных тестовых значений и соответствующих им эталонов:
•	действительные значения, используемые в качестве исходных тестов;
•	ожидаемые, эталонные выходные значения результатов тестирования;
•	ограничения по процедурам тестирования для каждого конкретного сценария.
Приводится спецификация конкретного сценария тестирования, которая идентифицирует все этапы, требуемые для работы системы в целом или компонента, и для выполнения контрольных сценариев, чтобы реализовать связанные с ними тесты. Выдается задание на верификацию и тестирование с указанием контролируемых параметров, исходных данных и результирующих эталонов. Выводятся результаты функционирования компонента тестирования при подготовленных тестах и заданиях. Производится сравнение результатов тестирования с эталонами и фиксируются обнаруженные отклонения (дефекты или ошибки) для проведения дополнительного тестирования с целью диагностики и локализации дефектов. Приводятся оценки полноты проведенного тестирования, степени покрытия компонента тестами выбранным методом и необходимости применения других методов и видов тестирования для увеличения покрытия тестами; оценка характеристик качества компонента, исходных и выходных данных в спецификациях и сценариях. Включаются оценки наличия ресурсов для продолжения тестирования и момента его завершения, а также для определения достигнутых характеристик качества компонента или выбора очередного метода тестирования. Наконец, сюда же включаются документы результатов процедур верификации и тестирования программы.
7.	План тестирования программного компонента начинается с указания цели, вида и назначения данного плана для конкретного компонента, перечисления и описания модулей и компонент подлежащих тестированию. Указывается назначение каждого тестового сценария, набор входных данных, условия исполнения тестов, ожидаемые
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
131
результаты, требуемые критерии покрытия и критерии полноты выполнения тестов. Приводятся пошаговые инструкции того, как каждый тестовый сценарий должен быть инициирован и выполнен, как должны быть оценены результаты тестирования и какая среда тестирования должна быть использована.
Одним из ключевых элементов плана является основной график выполнения работ, в котором перечисляются:
•	задачи исполнения каждого теста и сценарий проверки;
•	методы и критерии оценки качества тестирования;
•	входные и результирующие данные тестирования;
•	используемые ресурсы сценария тестирования.
Приводятся используемые технологические средства и методики тестирования; номенклатура и содержание оформляемых отчетных документов. Описывается взаимодействие плана тестирования компонентов с планами обеспечения качества и с управлением конфигурацией и корректировками компонентов и ПС в целом. Проводится детализация и документирование процесса тестирования на каждом этапе жизненного цикла ПС.
8.	Отчет о результатах верификации и тестирования компонентов (п. 3-7) включает в себя:
•	справку о передаче компонента на тестирование, когда в разработке участвуют независимые группы программистов и тестировщиков;
•	журнал выполнения плана тестирования, используемый бригадой тестировщиков;
•	результаты верификации и тестирования;
•	итоговый обобщенный отчет верификации и тестирования компонентов ПС.
9.	Методика комплексирования функциональных компонентов включает в себя тестирование идентичности исходного текста функционального компонента, представленного на носителе данных, с исходным текстом, представленным в программном документе на крупную функциональную задачу. А также проводится комплексиро-вание в статике модулей и компонентов, входящих и функциональный компонент, проверка интерфейсов между модулями и выявление их нестыковки с описаниями в спецификациях на функциональный компонент. Здесь производится устранение невязок интерфейсов между модулями и компонентами, входящими в функциональный компонент.
132
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Выполняется анализ потоков управления и установления степени покрытия тестами графовой модели функционального компонента при тестировании программы по выделенным маршрутам функционального компонента. Кроме того, приводится анализ потоков данных для установки связи наборов входных и выходных переменных программы, участвующих в исполнении функционального компонента по определенному маршруту, соответствие между областями определения наборов данных (входных и выходных) и маршрутами их обработки в функциональном компоненте.
Далее осуществляется оценка результатов тестирования, качества и корректности конкретного функционального компонента в статике без взаимодействия с другими функциональными компонентами. Подготавливаются тесты и сценарии для тестирования функционального компонента в статике, во взаимодействии с другими функциональными компонентами при некоторых постоянных значениях времени в соответствии с заданной временной диаграммой комплекса программ. Осуществляется комплексирование взаимодействия функционального компонента с другими компонентами и с базой данных вне реального времени.
Только после описанных выше процедур происходит подключение функционального компонента к операционной системе в реализующей ЭВМ и оценка возможности достаточно полного решения соответствующих функциональных задач в статике при постоянных значениях реального времени. Осуществляется завершение тестирования функционального компонента с другими группами программ, наращивание состава компонентов до полного комплекта реализуемых функциональных задач в ПС.
Далее проводится обработка результатов отладки, оценка качества и корректности функционального компонента во взаимодействии с другими группами в статике, формулируется вывод о достаточности данного набора тестов полностью проверить декларируемые в документах функциональные возможности. Подготавливается тестирование функционального компонента в реальном времени, сценарии тестирования и диаграммы изменения реального времени, которым соответствуют определенные содержания тестов в имитируемой внешней среде.
Тестирование качества функционального компонента завершается в реальном времени. Программы ввода-вывода и взаимодействия
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
133
с внешней средой, визуализации и организации всего вычислительного процесса также тестируются в реальном времени.
В заключение проводится обработка результатов тестирования и оценка качества функционального компонента в реальном времени, в полном его окружении с другими функциональными компонентами, удовлетворяющими критериям качества, передача от его разработчиков на комплексирование специалистам, ответственным за тестирование комплекса программ в целом.
10.	Оценка реализации комплексирования функциональных компонентов комплексов программ (п.9) состоит из следующих этапов:
•	удостоверение качества функционирования компонентов в соответствии с спецификациями требований, а также в критических ситуациях по условиям и логике решения задач (стрессовое тестирование) для испытаний исполнения функциональных компонентов в нештатных ситуациях;
•	определение корректности использования ресурсов памяти и производительности вычислительной системы при оценке качества и безопасности исполнения функциональных компонентов при ограниченности ресурсов ЭВМ;
•	оценка эффективности защиты функционального компонента от искажений исходных данных для выявления дефектов, проявляющихся при ложных или искаженных входных данных;
•	оценки эффективности защиты от сбоев аппаратуры и не выявленных ошибок программ и данных для проверки качества средств контроля и оперативного восстановления (рестарта) при различных, непреднамеренных искажениях функционирования компонентов ПС;
•	измерение достигнутых значений надежности и безопасности базовых версий функциональных компонентов ПС и определение основных характеристик качества комплекса программ;
•	оценка удобства эксплуатации и взаимодействия оператора пользователя с комплексом программ для обнаружения дефектов представления и отображения исходных и результирующих данных;
•	оценка удобства и качества инсталляции и подготовки пользовательских версий комплекса программ для выявления дефектов методов и средств адаптации функциональных компонентов ба
134
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
зовых версий к параметрам среды и конкретным условиям применения у пользователей;
•	оценка возможности и качества функционирования компонентов базовых версий комплекса программ, при реконфигурациях оборудования для обнаружения дефектов, проявляющихся при изменении состава или характеристик компонентов аппаратуры вычислительной системы или внешней среды;
•	оценка готовности функциональных компонентов комплекса программ к сопровождению и развитию версий путем настройки базовых версий на условия конкретного применения у пользователей, анализ удобства модифицирования и корректировки версий ПС;
•	контроль полноты и корректности документации, обнаружение и устранение ошибок несоответствия функциональных компонентов реального комплекса программы в ЭВМ, сопровождающей его технологической и эксплуатационной документации.
2.6.5. Документы квалификационного тестирования, испытаний и оценивания качества программных средств
1- Методика генерации тестов имитирующих внешнюю среду и обработку результатов квалификационного тестирования после выбора и установления статуса испытания ПС и соответствующих тестов подразумевает имитацию конкретных тестов с реальными характеристиками, адекватными объектам внешней среды. Здесь приводятся результаты математического моделирования внешней среды (поддержка процесса тестирования с помощью имитации данных из внешних для ПС компонентов системы). Производится регистрация характеристик тестовых данных на соответствие заданным обобщенным характеристикам каждого объекта внешней еды и исходным данным сеанса испытаний. Результаты оперативной обработки итогов испытаний тестируемого комплекса реального времени. Приводятся по упрощенным алгоритмам с большой пропускной способностью, обеспечивающей сохранение реального масштаба времени для испытываемого ПС. А также указываются результаты обобщающей обработки накопленных результатов испытаний вне реального времени после за-
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
135
вершения одного или серии испытаний характеристик качества функционирования ПС.
2. Методика применения проблемно-ориентированной системы квалификационного тестирования и испытаний комплексов программ. Осуществляется выделение требований и характеристик, подлежащих проверке при испытаниях функциональных компонентов и ПС в целом, обеспечивающих контроль проектных решений; выявление причин сбоев и отказов функционирования компонентов и ПС в целом. Определяются реальные характеристики качества функционирования системы и комплекса программ. Проводится проверка соответствия функционирования ПС и системы требованиям спецификаций и технического задания. Устанавливается необходимая продолжительность и режимы испытаний для достаточной проверки выполнения требований технического задания и соответствия предъявленной документации. Определяются тесты и реализация процесса тестирования разработчиком: ввод тестовых наборов; генерация тестовых данных; ввод ожидаемых, эталонных результатов. Производится выполнение участка тестируемой программы между контрольными точками, для которого вводимые данные могут быть отредактированы и включены в последующие тестовые сценарии. Тестовые результаты анализируются и обрабатываются. Используется возможность средств тестирования автоматически анализировать тестовые результаты: сравнение ожидаемых и реальных результатов; сравнение файлов; статистическую обработку результатов.
Проводится анализ покрытия тестами объектного кода комплекса программ для обнаружения операторов и процедур, которые не были вызваны, а также переменных, к которым не было ни одного обращения. Не обходится и без анализа производительности при исполнении комплекса программ: загрузки центрального процессора; загрузки памяти; обращения к специфицированным элементам данных или сегментам объектного кода; временные характеристики функционирования испытываемой программы.
3. Методика, содержание и сценарии квалификационного тестирования и испытаний программных средств состоит из содержания тестовых сценариев и процедур, которые используют для выполнения квалификационного тестирования системы или функциональных компонентов ПС.
Здесь проводятся следующие действия и оформляются документы:
136
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	план квалификационного тестирования комплекса программ;
•	квалификационное тестирование программного средства вне системы;
•	квалификационное тестирование характеристик качества системы с данным комплексом программ;
•	предварительные испытания главного конструктора - разработчика, которые могут совмещаться с завершением квалификационного тестирования функциональных компонентов, оформляются документально и являются основанием для предъявления заказчику на завершающие совместные, квалификационные испытания программного продукта;
•	опытная эксплуатация системы и комплекса программ разработчиками с участием испытателей и некоторых пользователей, назначаемых заказчиком (результаты могут учитываться при проведении совместных испытаний для их сокращения);
•	совместные, квалификационные испытания системы и комплекса программ комиссией заказчика и разработчика, в которой участвует главный конструктор разработки и некоторые ведущие разработчики, или аттестованной сертификационной лабораторие;
•	исходные документы комиссии при испытаниях;
•	отчет о квалификационном тестировании (испытаниях) ПС, выполненном для системы и комплекса программ.
4. Программа испытаний комплекса программ. В перечень входят конкретные проверки (решаемые задачи), которые следует осуществлять при испытаниях для подтверждения выполнения требований технического задания, спецификаций и нормативной документации, со ссылками на соответствующие разделы методик испытаний. Среди них - объект испытаний (компонент или комплекс программ), цель испытаний с указанием всех спецификаций требований, технического задания и характеристик качества ПС, подлежащих проверке; ограничения на проведение испытаний (экономические, технологические, временные, ресурсы специалистов). Перечисляются этапы жизненного цикла, на которых должно проводиться тестирование компонентов или ПС в целом.
Собственно, программа испытаний комплекса программ состоит из сдежующих документов:
•	перечень конкретных проверок, которые следует осуществлять при испытаниях для подтверждения выполнения требований спе
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
137
цификаций, технического задания и нормативной документации, со ссылками на соответствующие разделы методик испытаний;
•	план тестирования для последовательной проверки по всем разделам технического задания и дополнительным требованиям спецификаций, формализованным отдельными решениями разработчиков и заказчика;
•	сценарии проверок ПС соответствия техническому заданию и оценки степени выполнения требований функционального назначения системы и комплекса программ;
•	оценка комплектности, достаточности состава и качества документации на комплекс программ;
•	определение потребности в количестве и квалификации пользователей и обслуживающего персонала.
Основы методик испытаний, однозначно определяют содержание проверяемых характеристик, условия и сценарии тестирования функциональных компонентов и комплекса программ, а также инструментальные средства, используемые для автоматизации испытаний.
5.	Методики проведения испытаний комплекса программ по отдельным характеристикам качества состоят из следующих компонент.
Объект испытаний - полное наименование комплекса программ, обозначение и комплектность испытываемого функционального компонента или ПС в целом.
Цель испытаний - конкретные цели и задачи, которые должны быть достигнуты и решены в процессах испытаний.
Приводятся общие положения методов испытаний:
•	перечень руководящих документов, на основании которых проводят испытания;
•	место, внешняя среда и продолжительность испытаний;
•	идентификаторы организаций, участвующих в испытаниях;
•	перечень математических и комплексных моделей, применяемых для имитации внешней среды и оценки характеристик ПС;
•	перечень и результаты ранее проведенных испытаний;
•	перечень предъявляемых на испытания комплектов документов, откорректированных по результатам ранее проведенных испытаний.
Указываются объемы испытаний по разделам программы испытаний, условия и порядок проведения испытаний; материально
138
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
техническое и стендовое обеспечение испытаний комплекса программ; метрологическое обеспечение корректности испытаний с распределением задач и ответственности организаций и специалистов, участвующих в испытаниях, за выполнение соответствующих этапов, мероприятий и оценку характеристик комплекса программ.
Обязательно проводится отчетность и документирование результатов испытаний и оформляется акт содержания технического состояния ПС и системы после испытаний.
6.	Протоколы по результатам испытаний функциональных компонентов и/или комплекса программ включают в себя: идентификатор объекта испытаний; цель испытаний; назначение квалификационного тестирования и разделы требований спецификации, технического задания и программы, по которым проводились испытания. Приводится полный список должностных лиц и их квалификации, проводивших испытания, перечень пунктов программы испытаний, по которым они успешно проведены. Указывается перечень методик, в соответствии с которыми успешно проведены испытания, обработка и оценка результатов. Перечисляются условия и сценарии проведения квалификационного тестирования и характеристики исходных данных. Сюда же включаются отчет об отказах, сбоях и аварийных ситуациях, выявленных при испытаниях и отчет о корректировках параметров среды и объекта испытаний, комплекса программ и технической документации. Эти отчеты дополняются документами, в которых приводятся обобщенные результаты квалификационных испытаний с оценкой их на соответствие спецификациям требований технического задания и другим руководящим документам, а также технической документации; протоколы просмотров и аудитов, протоколы совещаний, регистрация отклонений от санкционированных процессов и протоколы проверки соответствия комплекса программ требованиям спецификаций.
В завершение делаются выводы о результатах испытаний и соответствии созданного комплекса программ и/или функционального компонента определенному разделу требований спецификаций и технического задания.
7.	Итоговый отчет результатов разработки программного средства (п. 1-6) включает в себя краткий обзор системы, включая описание ее функций и их подразделение на программную и аппаратную реализацию, архитектура, используемые процессоры, интерфейсы
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
139
аппаратных и программных средств, требования по обеспечению безопасности. Описывается фактически использованная модель жизненного цикла ПС; ссылки на документы жизненного цикла ПС, являющиеся выходными результатами процессов разработки и интегральных процессов комплекса программ. Приводятся функции ПС с акцентированием на обеспечение характеристик качества, безопасности и используемую концепцию разбиения компонентов ПС. Перечисляются основные характеристики ПС - размер исполняемого объектного кода, ограничения по времени и памяти, ограничения ресурсов разработки, значения и способы измерения каждой характеристики. Указывается связь между представляемыми документами комплекса программ и документами, определяющими систему, а также способы передачи комплекса документов жизненного цикла ПС заказчику.
Здесь же производится идентификация конфигурации ПС, посредством указания регистрационного номера и версии. Проводится обзор изменений и корректировок в ЖЦ ПС с указанием изменений, вызванных отказами, влияющими на качество и безопасность, с идентификацией изменений, выполненных после сдачи предыдущей версии. Выводится перечень сообщений о дефектах комплекса программ, не устраненных ко времени завершения испытаний, включая заявления о функциональных ограничениях ПС.
В заключении выдается утверждение о соответствии проекта требованиям стандартов и обзор методов, позволяющих доказать выполнение критериев, определенных в исходных данных проекта и планах ПС.
8.	Акт завершения работ по проекту программного средства. В этом документе приводятся основные результаты завершенного проекта ПС и выдается заключение о результатах завершенного проекта и степени выполнения технического задания и спецификаций требований к ПС с положительным или отрицательным итогом; даются рекомендации по развитию и внедрению результатов проекта ПС.
9.	Акт приемки программного средства в промышленную эксплуатацию включает в себя перечень систем и/или ПС, принимаемых в эксплуатацию; сведения о статусе приемочной комиссии (государственная, межведомственная, ведомственная), ее составе и основании для работы; перечень и наименования исходных документов, на основании которых разработано ПС. Здесь приводится состав и описание функций ПС, принимаемых в эксплуатацию. Указывается пере
140
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
чень и описание компонентов технического, программного, информационного и организационного обеспечения, принимаемых в эксплуатацию. Проводится оценка соответствия принимаемого ПС техническому заданию, спецификации требований и контракт на его создание. В заключении выдается решение комиссии о возможности принятия ПС в промышленную эксплуатацию и приводятся рекомендации комиссии по дальнейшему развитию системы и комплекса программ.
2.6.6.	Документы сопровождения
и конфигурационного управления версиями программного средства
1.	Описание среды жизненного цикла и конфигурации программного средства содержит информацию об аппаратной и программной средах разработки, генерации, повторной верификации или модификации ПС на протяжении всего жизненного цикла; инструментальных средствах разработки ПС: компиляторах, редакторах связей и загрузчиках, средствах обеспечения целостности данных; среде и методиках верификации и тестирования компонентов, используемых при корректировке программного средства. В частности, это информация об аттестованных инструментальных средствах обеспечения и корректировки жизненного цикла ПС и соответствующая документация об аттестации этих средств; идентификаторы конфигурации функциональных компонентов и программного средства; исходные тексты программ и исполняемый объектный код. Сюда же относятся и ранее разработанные компоненты ПС, если они используются в данном программном средстве. Здесь приводится комплекс технологических документов обеспечения жизненного цикла ПС; инструкции для компоновки исполняемого объектного кода, инструкции для компилирования и редактирования связей; процедуры, используемые для восстановления при регенерации, тестировании или модификации компонентов и ПС. Осуществляется контроль целостности данных для исполняемого объектного кода, проверяются документы управления конфигурацией, генерируемые в процессе управления конфигурацией, включая отчеты управления конфигурацией, указатели состояния конфигурации ПС и среды жизненного цикла комплекса программ.
2.	План управления конфигурацией программного средства подразумевает описание среды управления конфигурацией,
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
141
включая процедуры план-графика, инструментальные средства, методы, стандарты, организационную ответственность и интерфейсы специалистов; процессов управления конфигурацией в жизненном цикле ПС, которые обеспечивают реализацию целей данного процесса. Здесь приводятся компоненты изменения конфигурации, которые должны быть идентифицированы, методы идентификации документов жизненного цикла ПС, связь идентификации компонентов, ПС и системы. Осуществляется контроль изменений относительно базовой версии, обеспечивающей целостность компонентов конфигурации и базовой версии ПС. Приводятся методы оценки и определения приоритетов в устранении дефектов, утверждении изменений, реализации решений об изменениях и указывается связь этих методов с отчетами о дефектах и контролем изменений.
В заключение выдается отчет о текущем состоянии конфигурации, определение места хранения информации, характера ее воспроизведения для отчетов и порядка доступа к ней специалистов. Производится архивирование, получение из архива и выпуск официальной базовой версии ПС, контроль ее целостности. Указываются способы внесения информации в архив и получения из архива, определяется метод и полномочия для выпуска версии комплекса программ. Осуществляется контроль среды жизненного цикла, инструментальных средств для разработки, комплексирования, верификации, тестирования и загрузки ПС. На данном этапе определяется состав документов жизненного цикла ПС, генерируемых в процессе управления конфигурацией, включая отчеты управления конфигурацией компонентов, указатели состояния конфигурации и среды жизненного цикла ПС.
3.	Отчеты пользователей о выявленных дефектах и предложениях по корректировке комплекса программ подразделяются на следующие документы:
•	рекомендации пользователям по выявлению и регистрации условий проявления и содержания дефектов эксплуатируемых версий ПС;
•	идентификация и регистрация аномального поведения ПС, несогласованности процессов с планами и стандартами разработки, определение недостатков документации жизненного цикла ПС;
•	описание дефекта, достаточное для его понимания и устранения, описание возможных корректирующих действий, предназначенных для устранения зарегистрированного дефекта;
142
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	идентификатор пользователя, представившего отчет о дефектах и/или предложениях;
•	дата фиксирования дефекта или предложения на изменение ПС;
•	номер и параметры адаптации пользовательской версии ПС, на которой обнаружен дефект;
•	идентификация компонента конфигурации и/или этапа жизненного цикла ПС, где был обнаружен дефект;
•	подробное описание сценария и исходных данных, при которых выявлен дефект и документы результатов его регистрации;
•	предположение о причине, вызвавшей проявление дефекта;
•	идентификация компонента конфигурации, который необходимо модифицировать, или описание процесса, который должен быть изменен;
•	описание возможных корректирующих действий, предназначенных для устранения зарегистрированного дефекта;
•	предложение по модификации ПС и его компонентов для устранения дефекта или совершенствования функционирования программ.
4.	Описания выявленных дефектов и предложений по совершенствованию функций версии программного средства содержат результаты анализа предложения на выполнение изменения, причин и источника выявленного дефекта; рекомендации о возможных способах устранения дефекта или о реализации предложения по совершенствованию программ и базы данных. Публикуются оценки сложности, трудоемкости, эффективности и срочности модификации программ и базы данных; оценки влияния предлагаемых изменений на возможность эксплуатации версий ПС, имеющихся у пользователей.
5.	Описания подготовленных и утвержденных корректировок и обобщенных характеристик новой базовой версии программного средства подразумевают описание причины изменения программ и/или базы данных (дефект, совершенствование). Они включают в себя содержание изменений программ и базы данных; изменений документации на компоненты или версию ПС. Исследуется корректность результатов тестирования базовой версии ПС с разработанными изменениями.
Публикуются результаты испытаний модификации и обобщенные характеристики базовой версии ПС после внесения изменений. Выносятся решение по распространению пользователям результатов прове-
2.6, СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
143
денной модификации или новой версии ПС и решение по целесообразности сохранения сопровождения предшествующих версий ПС.
Указывается адрес хранения корректировок, документов и квалификационных тестов выполненной модификации и/или новой базовой версии ПС. Проводится идентификация новой конфигурации, протоколы об установлении новой базовой версии и ее регистрации в архиве. Осуществляется архивирование, получение из архива и выпуск официальной версии: контроль целостности базовой версии ПС, способы внесения информации в архив и получения из архива, метод и полномочия для выпуска версии комплекса программ.
В заключение, прикладываются отчеты об истории выполнения изменений версий ПС; протоколы о передаче новой версии ПС в архив и протоколы о выпуске новой версии ПС для применения пользователями.
6.	Извещение пользователям о выпуске новой версии программного средства и/или о прекращении сопровождения предшествующей версии происходит с помощью следующих документов:
•	краткое обоснование причин модификации или прекращения сопровождения версии ПС;
•	описание содержания и характеристики основных изменений в новой версии ПС;
•	рекомендации по корректировке, приобретению или замене пользовательской версии ПС.
7.	Описание новой базовой версии программного средства состоит из краткого обзора назначения и спецификации требований новой версии системы и ПС, указания особенностей истории разработки, эксплуатации и сопровождения системы и комплекса программ, идентификации заказчика, пользователей, разработчика, а также организации, осуществляющей сопровождение, регистрацию текущих и планируемых мест установки системы и ПС для пользователей. А также осуществляется идентификация физических носителей, содержащих новую зарегистрированную и утвержденную базовую версию ПС и связанную с ней документацию и идентификация комплекта новых зарегистрированных, утвержденных компьютерных файлов, содержащих базовую версию ПС. Приводится перечень всех изменений, внесенных в файлы и документы после выпуска предыдущей базовой вер-
144
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
сии ПС. Прикладываются полный комплект документов новой базовой версии ПС и инструкция по установке и инсталляции новой версии ПС.
8.	План передачи и внедрения новой базовой версии программного средства пользователям состоит из общего обзора результатов разработки, комплекта требований и особенностей новой базовой версии системы и ПС; заказчиков, пользователей, разработчиков и организаций, осуществляющих сопровождение, запланированные рабочие места и перечень передаваемых документов. Осуществляется контроль комплектности и состояния аппаратного и программного обеспечения, а также других ресурсов, необходимых для поддержки всего жизненного цикла передаваемого нового комплекса программ. Указываются запланированные сроки установки новой версии ПС у определенных пользователей.
Формируется комплект системы файлов и документов, относящихся к передаваемой новой базовой версии ПС. Выполняется детальное описание ресурсов, необходимых для инсталляции передаваемого ПС, требования к квалификации и составу персонала, чтобы специфицировать, разработать, документировать, тестировать, оценивать, контролировать, копировать и распространять новую базовую версию ПС. Документ сопровождается перечнем рекомендуемых мероприятий, в том числе консультаций и лекций, которые должен проводить разработчик в целях поддержки применения передаваемого нового ПС.
Осуществляется описание процесса подготовки персонала, который будет осуществлять поддержку передаваемого ПС: тематика, дата, продолжительность и место проведения теоретических и практических занятий.
Наконец, приводится порядок внедрения, включающий в себя все работы, необходимые при передаче и инсталляции новой версии ПС со стороны организаций, осуществляющих сопровождение.
9.	Отчет о результатах эксплуатации, снятой с сопровождения базовой версии программного средства и ее архивации содержит:
•	документ, обосновывающий прекращения сопровождения определенной базовой версии ПС и извещение пользователей (с указанием даты принятого решения);
•	идентификатор ответственного лица, принявшего решение о прекращении сопровождения определенной версии ПС;
2.6. СТРУКТУРА И СОДЕРЖАНИЕ ДОКУМЕНТОВ
145
•	дата и идентификатор лица, выполнившего архивацию определенной версии ПС;
•	идентификаторы физических носителей информации архива, содержащих подлинники и дубликаты файлов и документов, снятой с сопровождения базовой версии ПС.
10.	Отчет о результатах тиражирования базовых версий, конфигурациях и параметрах пользовательских версий программного средства содержит информацию об идентификаторах базовых версий ПС, поддерживаемых сопровождением и распространяемых пользователям; адреса архивов, содержащих физические носители файлов и документации каждой базовой версии ПС распространяемой пользователям; краткую характеристику и адреса архивов, содержащих квалификационные тесты базовых версий ПС. Приводится перечень идентификаторов пользователей, которым передана на эксплуатацию определенная базовая версия ПС. Указывается идентификатор базовой версии, которая адаптировалась для эксплуатации каждым пользователем. Перечисляются параметры среды пользователя, на которые адаптировалась определенная базовая версия ПС и характеристики активности обращений пользователей к поставщику за консультациями и модификациями комплекса программ.
2.6.7.	Документы процессов эксплуатации программных средств
1.	Общее описание системы, в которой используется программное средство: назначение, идентификатор; описание взаимосвязей программного продукта с другими системами и ПС; краткое описание ПС, перечень файлов, включая базу данных и файлы со справочной информацией для пользователей, описание аппаратуры и прочих ресурсов, необходимых для доступа и использования программного продукта в полном объеме. Приводятся режимы работы программного продукта; указываются терминалы, принтеры и другие входные и выходные устройства. Перечисляются необходимые процедуры, утилиты, в том числе процедуры для установки и инсталляции программного продукта. Указываются форматы представления входной и выходной информации, их назначение, тип, объем. Приводятся ограничения и наиболее типичные ошибки задания информации. Описывается используемая система управления базой данных.
146
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.	Общие требования к формированию Пользовательской документации программных средств по стандарту ISO 15910:1999 (ГОСТ Р-2002).
3.	Описание административного управления программными средствами системы состоит из краткой характеристики:
•	концепций и обзоров системного управления программами и базами данных;
•	документов, детализирующих концепцию процессов управления системой и ПС и требования к реализации каждой функции;
•	информационной модели системы, комплекса программ, их атрибутов и операций;
•	руководства для формализации и описания объектов управления системы и ПС;
•	формализации непосредственной передачи управляющей информации между компонентами системы и ПС;
•	документов, описывающих передаваемые типы данных и формализованные объекты, их состояния, атрибуты, операции и извещения об обмене;
•	классификатор объектов управления, отражающий взаимосвязь между классами объектов управления и правилами их применения;
•	функции администратора программных средств.
4.	Руководство системного администратора программного средства уже описывалось выше в разделе 2.2.9. Там же приведено и краткое содержание данного документа.
5.	Общее описание руководства пользователей программного средства, в том числе ссылки на другие руководства системы и комплекса программ и перечень и пояснение выводимых системой сообщений. Документ рассматривался в разделе 2.2.7.
6.	Руководство оперативного пользователя программного средства, в том числе гарантии и обязательства по контракту на комплекс программ, а также условия отказа от них; рекомендации по обучению и освоению ПС, включая описание контрольного примера, правила его запуска и выполнения; приложения детальные сведения о форматах исходных и результирующих данных, структуре файлов и экранов. Подробное описание руководства приводилось в разделе 2.2.6.
7.	Инструкция по формированию и ведению информации базы данных состоит из следующих документов:
2.7. СОСТАВ ПОЛЬЗОВАТЕЛЬСКОЙ ДОКУМЕНТАЦИИ
147
•	правила подготовки информации данных:
•	порядок и средства заполнения базы данных:
•	процедуры изменения и контроля информации базы данных:
•	порядок и средства восстановления информации базы данных.
8.	Паспорт на программное средство включает в себя:
•	общие сведения о программном средстве:
•	основные характеристики ПС:
•	комплектность: перечень эксплуатационных документов ПС; все непосредственно входящие в состав ПС компоненты; отдельные средства в комплексе программ, в том числе носители данных и эксплуатационные документы;
•	свидетельство (акт) о приемке;
•	гарантийные обязательства изготовителя (поставщика);
•	сведения о текущем состоянии комплекса программ;
•	сведения о выполнении регламентных, профилактических работ и их результатах.
9.	Пользовательская документация на коммерческие пакеты и закрытые коробки программных средств по стандарту ISO 9127, в том числе, документация внутри коробки, обучающая документация; документация для быстрых справок; документация на внешней упаковке пакета.
10.	Руководство по подготовке документации и обучению специалистов применению программного средства, в том числе:
•	виды и уровни обучения и категории персонала, требующие обучения применению программного средства;
•	требования к начальным квалификации и опыту, необходимым операторам, администраторам и техническому персоналу;
•	документация планов и требований по обучению специалистов;
•	руководства для обучения, включая материалы и средства автоматизации, используемые для обучения разных категорий специалистов;
•	план регулярного обучения персонала, контроля и учета результатов обучения с методами оценки достигнутой квалификации специалистов;
•	требования и содержание сертификата специалиста, гарантирующего, что соответствующие категории обученного персонала готовы для выполнения запланированных действий и решения задач с применением определенного программного средства.
148
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.7. Состав пользовательской документации на программное средство
Документация подобна страхованию на неопределенный срок.
Она удовлетворяет всех, поскольку почти никто из подписавшихся на нее не зависит от ее преимуществ.
(Алан Дж.Перлис)
В отличие от технической документации, сфокусированной на коде и том, как он работает, пользовательская документация описывает лишь то, как использовать программу.
В случае если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так.
Обычно, пользовательская документация представляет из себя руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идет еще дальше и предоставляет инструкции о том что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь четкую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.
Существует три подхода к организации пользовательской документации.
•	Вводное руководство, наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач.
•	Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей.
2.7. СОСТАВ ПОЛЬЗОВАТЕЛЬСКОЙ ДОКУМЕНТАЦИИ
149
•	Команды или задачи организованы в виде алфавитного справочника - часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут.
Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей.
Во многих случаях разработчики программного продукта ограничивают набор пользовательской документации лишь встроенной системой помощи, содержащей справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей и поддержке совершенствующихся пользователей перекладывается на частных издателей, часто оказывающих значительную помощь разработчикам. Стиль изложения - одно из наиболее сложно формализуемых качеств документации пользователя. Вместе с тем, любой читатель отличает плохо написанный текст от хорошо написанного- Если текст перегружен длинными сложно построенными фразами, в нем много неясностей, двусмысленностей, непоследовательно используется терминология, затруднен поиск нужных сведений, то работать с ним тяжело. Даже если содержание этого текста ценно, полезность его из-за трудности восприятия сильно снижается.
Не имея требований к стилю, можно уповать только на добродетели конкретного автора, на его старательность, опыт, вкус и литературные способности. При промышленном производстве программных продуктов такой подход слишком ненадежен. В случае совместной работы коллектива добросовестных и талантливых авторов над одним комплектом технической документации необходимо добиться от них если не полного единообразия, то хотя бы единства стиля изложения в его основных чертах [26].
Встречная проблема заключается в том, что объективно хорошо написанный текст, функционально полностью соответствующий своим задачам, может просто не понравиться представителю заказчика, вызвать у него неприятие на уровне личного вкуса. Предлагаемый стандарт мыслится как инструмент для преодоления упомянутых затруднений и безболезненного урегулирования (а еще лучше, предотвращения) споров о качестве текста документации.
Рассмотрим очень сжатый свод правил и советов для разработчиков технической документации [22]. Прежде всего, он относится к документации пользователя программного продукта, хотя некоторые
150
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
положения могут быть расширены и применены к документации других типов. Перечень затронутых здесь вопросов нельзя назвать исчерпывающим, однако, руководствуясь этим документом, разработчики смогут создавать хотя бы поверхностно правильно структурированные и оформленные эксплуатационные документы, а также добиться соблюдения единого стиля при работе в команде.
2.7 Д. Предмет документирования
Разработка технической документации подразумевает четкое выделение предмета документирования и его границ. Предметом документирования может быть, например, программа или программный комплекс, определенная комплектация поставки программного комплекса, платформа для разработки программ или систем определенного типа и т.п.
У предмета документирования должны быть четкие обозначения, в том числе:
•	официальное полное наименование;
•	номер версии, дата выпуска или другие данные, идентифицирующие конкретное состояние предмета документирования, которое будет зафиксировано в документации.
В идеале предмет должен быть защищен от изменений во время документирования. На практике добиться этого обычно не получается. Во всяком случае, процесс документирования должен быть организован таким образом, чтобы любое изменение в предмете оперативно доводилось до сведения разработчика документации.
2.7.2.	Комплект документации. Документ
Техническая документация реализуется в форме комплекта, состоящего из определенных документов.
Каждый документ имеет свой собственный предмет, который может совпадать с предметом документирования в целом или представляет собой часть предмета документирования (модуль, компонент и т.п.).
При написании любого документа принимаются во внимание характеристики его типичного читателя, в первую очередь:
•	квалификация в предметной области;
2.7. СОСТАВ ПОЛЬЗОВАТЕЛЬСКОЙ ДОКУМЕНТАЦИИ
151
•	квалификация в области информационных технологий;
•	состав задач, решаемых с помощью предмета документирования;
•	предоставленные читателю права доступа к тем или иным данным, функциям, объектам.
Предполагается, что целевая аудитория документа едина по перечисленным характеристикам. Каждый документ должен содержать информацию, необходимую его целевой аудитории для решения поставленных перед ней задач. При этом информация в документе должна быть представлена в форме, наиболее удобной этой целевой аудитории.
Часто оказывается, что персонал, работающий с программным продуктом, достаточно разнороден, так что можно выделить не одну, а несколько целевых аудиторий (пользователи, специалисты по сопровождению, администраторы и др.), для каждой из которых разрабатывается свой набор документов.
Документы бывают разных типов (жанров, разновидностей), в зависимости от характера представленных в них сведений и порядка изложения последних. Известны такие типы документов, как руководство пользователя, руководство администратора, руководство программиста, описание применения и т.д. Распространенные системы стандартов (международных, национальных, отраслевых), а также стандарты, принятые в организациях и на предприятиях, как правило, предусматривают формирование комплекта из разнотипных документов, что позволяет описать предмет документирования всесторонне.
При разработке документа принимается решение о том, с какой подробностью в нем будут изложены сведения: максимально полно или избирательно. Решение об избирательном изложении сведений связано главным образом с характеристиками целевой аудитории.
Итак, основными характеристиками документа являются:
•	предмет документа;
•	тип документа;
•	подробность изложения.
Предмет документа определяется в основном поставленной перед техническим писателем задачей. Тип документа определяется необходимостью предоставления читателю тех или иных сведений для успешной эксплуатации предмета. Подробность изложения сведений в документе определяется способом адаптации документа к нуждам целевой аудитории.
152
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Документ обязательно должен быть озаглавлен. Если форма, в которой это следует делать, не регламентирована используемым стандартом, рекомендуется, чтобы в заголовке документа упоминались его предмет и тип, например: «Утилиты для работы с диском. Руководство пользователя», «Утилиты для работы с диском. Руководство по установке».
2.7.3.	Формальная структура документа
Документ делится на структурные элементы разного уровня: разделы, подразделы, пункты, подпункты и т.д. Каждому структурному элементу должен быть присвоен заголовок. Текст, не разделенный на структурные элементы, называется сплошным.
Состав разделов и порядок их следования, как правило, определяется типом документа и может быть взят из применяемого стандарта. Состав структурных элементов следующих уровней определяется содержательными соображениями, в частности, правилами расположения информации разного типа.
На количество разделов в документе ограничений не накладывается. Количество подразделов внутри раздела, пунктов внутри подраздела и т.д. рекомендуется ограничить девятью. Глубину вложенности структурных элементов рекомендуется ограничить четырьмя (т.е. избегать деления подпунктов на более мелкие структурные элементы).
2.7.4.	Типы информации в документе
Информация, излагаемая в документе, может быть разделена на три типа.
•	Структурная информация касается понятийного аппарата предметной области и предмета документирования, рассматриваемых в документе явлений и взаимосвязей между ними.
•	Процедурно-функциональная информация касается решения пользовательских задач и применения пользователем функциональных возможностей программного продукта.
•	Справочная информация - это всевозможные вспомогательные сведения о функциях, параметрах, режимах работы и т.п.
Информацию разных типов рекомендуется располагать в следующем порядке: сначала структурная информация, затем процедурно
2.7. СОСТАВ ПОЛЬЗОВАТЕЛЬСКОЙ ДОКУМЕНТАЦИИ
153
функциональная и в заключение справочная. Эта рекомендация относится и к документу в целом (на уровне разделов, подразделов и т.д.), и к отдельным его частям (на уровне сплошного текста).
Наибольший объем текста в документе обычно приходится на процедурно-функциональную информацию. Структурная и справочная информация при всей их важности носят вспомогательный характер: структурная информация предваряет, а справочная уточняет процедурно-функциональную.
Следует уже при составлении структуры документа принять решение о том, какой общий принцип будет лежать в основе изложения сведений - процедурный или функциональный. Выбор общего принципа осуществляется не произвольно, а на основании существенных соображений. Если в документе описывается решение ряда конкретных пользовательских задач, и для каждой задачи излагается пошаговый порядок ее решения, лучше работает процедурный принцип. Если состав задач пользователя заранее неизвестен, в документе приходится описывать отдельные функциональные возможности и способы их применения в различных ситуациях. Тогда удобнее функциональный принцип.
Выбрав один из принципов изложения сведений, необходимо последовательно придерживаться его. Исключения допускаются при написании тех разделов, для которых выбранный принцип не подходит. Главным образом, речь идет о написании разделов, посвященных настройке, конфигурированию и обслуживанию программы, - для этих разделов всегда предпочтителен функциональный принцип.
2.7.5.	Изложение материала в сплошном тексте
Сплошной текст должен быть разбит на хорошо обозримые абзацы. Рекомендуется, чтобы размер большинства абзацев не превышал одну восьмую страницы.
Также рекомендуется воздерживаться от написания длинных и синтаксически сложных предложений. Если удается разделить предложение на два других, не сделав хотя бы одно их них противоестественно коротким, то в общем случае лучше заменить его двумя логически связанными предложениями.
Перечисление компонентов, функций, возможностей, любых других однородных объектов или категорий следует оформлять в виде
154
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
списка. Если пункты перечисления объективно не упорядочены, следует использовать маркированный список. Если пункты перечисления объективно образуют последовательность, следует использовать нумерованный список с численной нумерацией. Если пункты перечисления объективно не упорядочены, но необходимо на них ссылаться из текста, можно использовать нумерованный список с буквенной нумера-цией. Если оказывается, все пункты списка, во-первых, относительно объемны, и, во-вторых, имеют одинаковую структуру, рекомендуется оформить перечисление не списком, а таблицей.
Структурная информация должна формировать у читателя системное представление обо всех понятиях, явлениях и взаимосвязях, на которые опирается изложение процедурно-функциональной и справочной информации. Однако нет необходимости явно вводить понятия, явления и взаимосвязи, заведомо знакомые целевой аудитории в силу ее квалификации или бытового опыта.
Структурная информация должна излагаться в следующем порядке: от заведомо известного читателю к неизвестному. Каждое следующее понятие должно раскрываться через заведомо известные читателю или ранее введенные в тексте понятия. Системные взаимосвязи желательно описывать только после того, как все участвующие в них объекты или явления будут представлены читателю.
Структурная информация не должна быть избыточной. Не надо вводить и разъяснять понятия, которые в дальнейшем не используются. Не надо сообщать о явлениях больше, чем необходимо целевой аудитории для решения поставленных перед ней задач.
Под процедурной информацией подразумевается описание действий пользователя по решению определенной пользовательской задачи. Процедурная информация обычно излагается в предположении, что пользователь решает с помощью программы обозримое число пользовательских задач и для каждой задачи нуждается в пошаговом описании ее решения.
Каждую пользовательскую задачу рекомендуется описывать по следующему плану.
1.	Постановка пользовательской задачи. Описание достигаемого результата (например, набора выходных данных) и его смысла с точки зрения пользователя, описание входных данных и начальных условий, предупреждения о возможных неожиданных или негативных последствиях (если они возможны).
2.7. СОСТАВ ПОЛЬЗОВАТЕЛЬСКОЙ ДОКУМЕНТАЦИИ
155
2.	Пошаговое описание процедуры решения пользовательской задачи. Каждый шаг, совершаемый пользователем, оформляется в виде пункта нумерованного списка. В отдельный шаг процедуры рекомендуется включать непрерывные во времени действия пользователя, вызывающие значимую реакцию системы, например, выбор некоторого пункта меню, заполнение и оправка формы, нажатие комбинации «горячих» клавиш и т.п. Описание каждого шага должно в общем случае состоять из следующих частей:
•	описание как таковых действий пользователя (обязательно);
•	описание реакции системы в случае успеха (обязательно);
•	описание возможных ошибок и способов их устранения (если есть).
При описании действий пользователя изложение должно идти на уровне конкретных элементов интерфейса, однозначно идентифицируемых пользователем по заголовкам или внешнему виду: экранных форм, полей, кнопок, пиктограмм, пунктов меню и т.п.
3.	Дополнительные сведения: рассмотрение второстепенных вариантов выполнения процедуры в случае ее ветвления, справочные таблицы и т.п.
Под функциональной информацией подразумевается описание возможностей программы. Функциональная информация обычно излагается в предположении, что пользователь самостоятельно формулирует задачи и, владея данной информацией, в состоянии найти пути их решения.
Каждую функциональную возможность рекомендуется описывать по следующему плану:
•	наименование функциональной возможности;
•	элемент пользовательского интерфейса, предоставляющий доступ к функциональной возможности;
•	указания по применению функциональной возможности (могут быть изложены в форме краткой процедуры).
Описания взаимосвязанных или однотипных функциональных возможностей рекомендуется собирать в таблицу, где каждой функциональной возможности отведена одна строка. Каждый столбец таблицы соответствует пункту приведенного выше плана описания.
156
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Справочную информацию рекомендуется излагать в форме, которая обеспечивает читателю наибольшее удобство при поиске нужных сведений. Часто такой формой оказывается таблица.
Структурную информацию рекомендуется выносить в начало сплошного текста, чтобы ввести читателя в курс дела до того, как он начнет действовать.
Допускается включать в описание шага процедуры обозримые блоки функциональной информации. Например, описание шага, который заключается в заполнении формы, можно сопроводить таблицей, описывающей ее отдельные поля.
Справочную информацию рекомендуется выносить в конец сплошного текста, а при значительном объеме в отдельные структурные элементы в конце документа, например в приложения.
2.7.6.	Слова и формулировки
Словарь документации пользователя должен быть жестко ограничен рамками решаемой задачи. Следует обратить внимание на следующие группы слов.
Терминология - как компьютерная, так и относящаяся к предметной области - должна употребляться во всей документации единым образом: термин не может употребляться в различных значениях, а два термина не могут употребляться в одном и том же значении.
Вспомогательная терминология. Сюда относятся разного рода отвлеченные слова, не являющиеся собственно терминами, но служащие для описания работы программ и действий пользователя, например: открывать (что-либо для редактирования), протекать (о процессе), редактировать (о данных) и т.д. Сюда же относятся обобщающие слова для программных продуктов, групп персонала, объектов обработки и т.д. Следует использовать в одинаковых (сходных) ситуациях одинаковые (сходные) слова и выражения.
Слова-«артикли». Слова вроде * соответствующий», «данный», «вышеупомянутый» и другие, используемые для указания и уточнения, не рекомендуются к употреблению и используются только в случае крайней необходимости, поскольку они только загромождают текст. Следует использовать прямые и конкретные указания на объекты и функции - по имени или другому идентификатору.
2.7. СОСТАВ ПОЛЬЗОВАТЕЛЬСКОЙ ДОКУМЕНТАЦИИ
157
Формулировки, используемые в документации, должны отвечать следующим требованиям.
Строгость. Следует использовать только терминологические, а не расплывчатые общие именования, употреблять технически грамотные выражения, не допускать высказываний слишком узких или слишком широких по смыслу.
Лаконичность. Следует стремиться высказывать мысль с употреблением минимума лишних слов.
Завершенность. Следует проговаривать все аспекты той или иной ситуации, а не рассчитывать на догадливость пользователя. Например, не «передача в другой формат», а «передача данных из внутреннего формата программы в другой формат».
Однозначность. Следует использовать выражения, не допускающих многозначных толкований. Особое внимание следует обратить внимание на употребление модальных глаголов и слов «мочь», «хотеть», «быть должным», «быть необходимым» и проверять себя - всегда ли пользователь правильно понимает их смысл. Слова и выражения, обозначающие желание, долженствование, запрет, не рекомендуется употреблять в документации пользователя программного продукта, хотя в технологических инструкциях, действующих в конкретной организации, «должен» и «запрещается» вполне допустимы.
Для унификации употребления основной и вспомогательной терминологии, а также для использования отточенных формулировок рекомендуется в каждой организации вести словарь устойчивых формул для описания сходных ситуаций - фигур описания.
2.7.7.	Авторская разметка текста
В тексте технической документации на программы принято оформлять врезками следующие сведения:
•	предупреждения о неочевидных или неожиданных последствиях действий пользователя;
•	предостережения о возможных негативных последствиях действий пользователя;
•	критически важные сведения, пренебрежение которыми может привести к ошибкам;
•	полезные дополнительные сведения, например, советы пользова-
телю.
158
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Предупреждения и предостережения обязательно должны располагаться в тексте перед описанием тех действий, к которым они относятся.
В тексте технической документации на программы принято выделять шрифтом следующие фрагменты (табл. 2.2).
Таблица 2.2. Выделенный текст
Тип выделенного текста	Принятый способ выделения
Вводимые термины	курсив
Наименования элементов интерфейса	полужирный шрифт
Обозначения клавиш и их комбинаций	полужирный шрифт, ПРОПИСНЫЕ буквы
Строки, вводимые пользователем с клавиатуры, значения и другие литералы	моноширинный шрифт, например Courier New
2.8. Техническое задание
на проектирование
У каждой программы (по крайней мере) два назначения: что она должна делать и чего не должна.
(Алан Дж.Перлис)
Мыслить по шаблону - вернейший способ завалить дело.
(Джон Энрайт)
Техническое задание (ТЗ) - исходный документ для проектирования сооружения или промышленного комплекса, конструирования технического устройства (прибора, машины, системы управления и т.д.), разработки информационных систем, стандартов либо проведения научно-исследовательских работ (НИР) [30].
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
159
ТЗ содержит основные технические требования, предъявляемые к сооружению, изделию или услуге и исходные данные для разработки. В ТЗ указываются назначение объекта, область его применения, стадии разработки конструкторской (проектной, технологической, программной и т.п.) документации, ее состав, сроки исполнения и т.д., а также особые требования, обусловленные спецификой самого объекта либо условиями его эксплуатации. Как правило, ТЗ составляют на основе анализа результатов предварительных исследований, расчетов и моделирования.
Как инструмент коммуникации в связке общения заказчик-исполнитель, техническое задание позволяет [30]:
• обеим сторонам:
—	представить готовый продукт;
—	выполнить попунктную проверку готового продукта (приемочное тестирование и проведение испытаний);
—	уменьшить число ошибок, связанных с изменением требований в результате их неполноты или ошибочности (на всех стадиях и этапах создания, за исключением испытаний);
• заказчику:
—	осознать, что именно ему нужно, в т.ч. опираясь на существующие на данный момент технические возможности и свои ресурсы;
—	требовать от исполнителя соответствия продукта всем условиям, оговоренным в ТЗ;
• исполнителю:
—	понять суть задачи, показать заказчику «технический облик» будущего изделия, программного изделия или автоматизированной системы;
—	спланировать выполнение проекта и работать по намеченному плану;
—	отказаться от выполнения работ, не указанных в ТЗ.
Техническое задание - исходный документ, определяющий порядок и условия проведения работ по Договору, содержащий цель, задачи, принципы выполнения, ожидаемые результаты и сроки выполнения работ.
160
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Техническое задание является исходным материалом для создания информационной системы или другого продукта. Поэтому ТЗ в первую очередь должно содержать основные технические требования к продукту и отвечать на вопрос, что данная система должна делать, как работать и при каких условиях.
Как правило, этапу составления технического задания предшествует проведение обследования предметной области, которое завершается созданием аналитического отчета. Именно аналитический отчет (или аналитическая записка) ложится в основу документа * Техническое задание» [31].
Если в отчете требования заказчика могут быть изложены в общем виде и проиллюстрированы UML-диаграммами, в техническом задании следует подробно описать все функциональные и пользовательские требования к системе. Чем подробнее будет составлено техническое задание, тем меньше спорных ситуаций возникнет между заказчиком и разработчиком во время приемочных испытаний.
Таким образом, техническое задание является документом, который позволяет как разработчику, так и заказчику представить конечный продукт и впоследствии выполнить проверку на соответствие предъявленным требованиям.
Руководствующими стандартами при написании технического задания являются ГОСТ 34.602.89 * Техническое задание на создание автоматизированной системы» и ГОСТ 19.201-78 «Техническое задание. Требования к содержанию и оформлению». Первый стандарт предназначен для разработчиков автоматизированных систем, второй для программных средств.
2.8.1.	ГОСТ 19.201-78. Техническое задание.
Требования к содержанию и оформлению
Настоящий стандарт устанавливает порядок построения и оформления технического задания на разработку программы или программного изделия для вычислительных машин, комплексов и систем независимо от их назначения и области применения.
Стандарт полностью соответствует СТ СЭВ 1627-79.
1.	ОБЩИЕ ПОЛОЖЕНИЯ
1.1.	Техническое задание оформляют в соответствии с ГОСТ 19.106-78 на листах формата 11 и 12 по ГОСТ 2.301-68, как правило,
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
161
без заполнения полей листа. Номера листов (страниц) проставляются в верхней части листа над текстом.
1.2.	Лист утверждения и титульный лист оформляют в соответствии с ГОСТ 19.104-78.
Информационную часть (аннотацию и содержание), лист регистрации изменений допускается в документ не включать.
1.3.	Для внесения изменений или дополнений в техническое задание на последующих стадиях разработки программы или программного изделия выпускают дополнение к нему. Согласование и утверждение дополнения к техническому заданию проводят в том же порядке, который установлен для технического задания.
1.4.	Техническое задание должно содержать следующие разделы:
•	введение;
•	основания для разработки;
•	назначение разработки;
•	требования к программе или программному изделию;
•	требования к программной документации;
•	технико-экономические показатели;
•	стадии и этапы разработки;
•	порядок контроля и приемки;
•	в техническое задание допускается включать приложения.
В зависимости от особенностей программы или программного изделия допускается уточнять содержание разделов, вводить новые разделы или объединять отдельные из них.
2.	СОДЕРЖАНИЕ РАЗДЕЛОВ
2.1.	В разделе «Введение» указывают наименование, краткую характеристику области применения программы или программного изделия и объекта, в котором используют программу или программное изделие.
2.2.	В разделе «Основания для разработки» должны быть указаны:
•	документ (документы), на основании которых ведется разработка;
•	организация, утвердившая этот документ, и дата его утверждения;
•	наименование и (или) условное обозначение темы разработки.
2.3.	В разделе «Назначение разработки» должно быть указано функциональное и эксплуатационное назначение программы или программного изделия.
162
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.4.	Раздел «Требования к программе или программному изделию» должен содержать следующие подразделы:
•	требования к функциональным характеристикам;
•	требования к надежности;
•	условия эксплуатации;
•	требования к составу и параметрам технических средств;
•	требования к информационной и программной совместимости;
•	требования к маркировке и упаковке;
•	требования к транспортированию и хранению;
•	специальные требования.
2.4.1.	В подразделе «Требования к функциональным характеристикам» должны быть указаны требования к составу выполняемых функций, организации входных и выходных данных, временным характеристикам и т.п.
2.4.2.	В подразделе «Требования к надежности» должны быть указаны требования к обеспечению надежного функционирования (обеспечения устойчивого функционирования, контроль входной и выходной информации, время восстановления после отказа и т.п.).
2.4.3.	В подразделе «Условия эксплуатации» должны быть указаны условия эксплуатации (температура окружающего воздуха, относительная влажность и т.п. для выбранных типов носителей данных), при которых должны обеспечиваться заданные характеристики, а также вид обслуживания, необходимое количество и квалификация персонала.
2.4.4.	В подразделе «Требования к составу и параметрам технических средств» указывают необходимый состав технических средств с указанием их основных технических характеристик.
2.4.5.	В подразделе «Требования к информационной и программной совместимости» должны быть указаны требования к информационным структурам на входе и выходе и методам решения, исходным кодам, языкам программирования и программным средствам, используемым программой. При необходимости должна обеспечиваться защита информации и программ.
2.4.6.	В подразделе «Требования к маркировке и упаковке» в общем случае указывают требования к маркировке программного изделия, варианты и способы упаковки.
2.4.7.	В подразделе «Требования к транспортированию и хранению» должны быть указаны для программного изделия условия транс-
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
163
портирования, места хранения, условия хранения, условия складирования, сроки хранения в различных условиях.
2.5а. В разделе «Требования к программной документации» должен быть указан предварительный состав программной документации и, при необходимости, специальные требования к ней.
2.5.	В разделе «Технико-экономические показатели» должны быть указаны: ориентировочная экономическая эффективность, предполагаемая годовая потребность, экономические преимущества разработки по сравнению с лучшими отечественными и зарубежными образцами или аналогами.
2.6.	В разделе «Стадии и этапы разработки» устанавливают необходимые стадии разработки, этапы и содержание работ (перечень программных документов, которые должны быть разработаны, согласованы и утверждены), а также, как правило, сроки разработки и определяют исполнителей.
2.7.	В разделе «Порядок контроля и приемки» должны быть указаны виды испытаний и общие требования к приемке работы.
2.8.	В приложениях к техническому заданию, при необходимости, приводят:
•	перечень научно-исследовательских и других работ, обосновывающих разработку;
•	схемы алгоритмов, таблицы, описания, обоснования, расчеты и другие документы, которые могут быть использованы при разработке;
•	другие источники разработки.
Итак, документ «Техническое задание» должен, по сути, отражать все требования к проектируемому продукту, выделенные на этапе аналитического исследования объекта автоматизации, В следующих двух подразделах приведены примеры написания технического задания: простейший, описывающий работу элементарного текстового редактора; и пример из личной практики автора данного пособия. Заметим, что в обоих случаях нет строгого следования требованиям ГОСТ, но в то же время сохранена структура документа, определенная приведенным стандартом.
164
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.8.2.	Простейший пример технического задания
1.	ВВЕДЕНИЕ
1.1.	Наименование программного изделия
Полное наименование программы - «Простейший редактор текстовых файлов для Windows». Краткое наименование программы - редактор.
1.2.	Область применения
Редактор предназначен для корректировки уже имеющихся и создания новых текстовых файлов в диалоговом режиме работы. Редактор может применяться для работы с файлами, сохраненными в текстовом формате, при написании исходных текстов программ.
2.	ОСНОВАНИЕ ДЛЯ РАЗРАБОТКИ
2.1.	Документ, на основании которого ведется разработка
Разработка ведется на основании зачетного задания по дисциплине «Документирование программного обеспечения».
2.2.	Организация, утвердившая этот документ, и дата его утверждения.
Задание утверждено на заседании кафедры «Программирование» 05.03.2012 и выдано преподавателем кафедры Ивановым И.И.
2.3.	Наименование темы разработки
Наименование темы разработки - TextEditor.
3.	НАЗНАЧЕНИЕ РАЗРАБОТКИ
Разработка является зачетной работой по курсу.
4.	ТРЕБОВАНИЯ К ПРОГРАММЕ
4.1.	Требования к функциональным характеристикам
4.1.1.	Состав выполняемых функций
4.1.1.1.	Редактор должен обеспечить корректировку уже имеющихся на диске и создание новых текстовых файлов в диалоговом режиме работы.
4.1.1.2.	Внешний вид программы должен соответствовать экранным формам и сценарию работы, представленным в ПРИЛОЖЕНИИ 1.
4.1.1.3.	Список управляющих клавиш программы редактора и кодов символов, заносимых в текстовый файл, должен соответствовать ПРИЛОЖЕНИЮ 2.
4.1.1.4.	При запуске редактора с помощью файла WinTextEdit.exe программа должна обеспечить загрузку рабочего окна редактора. За-
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
165
грузка и сохранение файла осуществляется через главное меню программы.
4.1.1.5.	В любой момент работы программы при нажатии клавиши F1 либо при выборе пункта «Помощь» главного меню должны выводиться тексты файлов помощи со списком всех возможных команд редактора на данный момент.
4.1.1.6.	Программа должна обеспечить вывод на принтер содержимого текстового файла стандартными символами принтера с размером шрифта, заданным пользователем.
4.1.2.	Организация входных и выходных данных
Организация входных и выходных файлов редактора должна соответствовать ПРИЛОЖЕНИЮ 3. Размер редактируемого файла не должен превышать 64 Кб. Число символов в строке произвольно.
В процессе работы редактора входной информации для программы должны являться коды клавиш, нажимаемых пользователем на клавиатуре, согласно режимам, определяемым выходной информацией.
4.1.3.	Временные характеристики и размер занимаемой памяти
Время реакции программы на нажатие любой из клавиш не должно превышать 0.25 с, за исключением реакций на чтение и запись входных и выходных файлов. Объем занимаемой оперативной памяти не должен превышать 200 Кб.
4.2.	Требования к надежности
4.2.1.	Требования к надежному функционированию
Программа должна нормально функционировать при бесперебойной работе ЭВМ. При возникновении сбоя в работе аппаратуры восстановление нормальной работы программы должно производиться после:
1)	перезагрузки операционной системы;
2)	запуска исполняемого файла программы; повторного выполнения действий, потерянных до последнего сохранения информации в файл на диске.
Уровень надежности программы должен соответствовать технологии программирования, предусматривающей:
1)	инспекцию исходных текстов программы;
2)	автономное тестирование модулей программы;
3)	тестирование сопряжений модулей программы;
4)	комплексное тестирование программы.
4.2.2.	Контроль входной и выходной информации
166
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Программа должна контролировать выбор пользователем пункта меню «Выход» и предупреждать о возможной потере несохраненных изменений.
4.2.3.	Время восстановления после отказа
Время восстановления после отказа должно состоять из:
1)	времени запуска пользователем исполняемого файла программы;
2)	времени повторного ввода потерянных данных.
4.3.	Условия эксплуатации
Программа должна храниться в виде двух маркированных копий: эталонной и рабочей. Периодическая перезапись информации должна осуществляться согласно нанесенной маркировке. Условия хранения дисков с программой должны соответствовать нанесенной на них маркировке.
4.4.	Требования к составу и параметрам технических средств
Программа должна корректно работать на следующем или совместимом с ним оборудовании:
1)	персональный компьютер с процессором Pentium и выше;
2)	принтер.
4.5.	Требования к информационной и программной совместимости
4.5.1.	Требования к информационным структурам на входе и выходе
Требования к информационным структурам на входе и выходе определены в п.4.1.2.
4.5.2.	Требования к методам решения
Требования к методам решения определены в пп.4.1.1.2. Внутренний буфер редактора должен помещать самый длинный редактируемый файл целиком. Выбор остальных методов решения осуществляется разработчиком без согласования с заказчиком.
4.5.3.	Требования к языкам программирования
Язык программирования выбирается разработчиком без согласования с заказчиком.
4.5.4.	Требования к программным средствам, используемым программой
Для работы программы необходима операционная система Windows ХР и выше.
4.6.	Требования к маркировке и упаковке
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
167
Диски с эталонным и рабочими экземплярами программы должны иметь маркировку, состоящую из надписи «TextEditor», надписи «эталон» или «рабочая», даты последней перезаписи программы. Упаковка должна соответствовать условиям хранения диска. На упаковке должны быть указаны условия транспортирования и хранения диска.
4.7.	Требования к транспортированию и хранению
Условия транспортирования и хранения диска должны соответствовать п. 4.6.
5.	ТРЕБОВАНИЯ К ПРОГРАММНОЙ ДОКУМЕНТАЦИИ
Состав программной документации должен включать следующие документы:
1)	технический проект программы по ГОСТ 19.404-79 в машинописном исполнении;
2)	описание программы по ГОСТ 19.402-78 на компакт-диске;
3)	текст программы по ГОСТ 19.401-78 на компакт-диске;
4)	руководство программиста по ГОСТ 19.504-79 на компакт-диске в виде файла README.TXT.
Пояснительная записка «Технический проект программы» должна содержать следующие разделы.
1.	Раздел «Входные данные» (характер, организация и предварительная подготовка входных данных).
2.	Раздел «Выходные данные» (характер и организация выходных данных).
3.	Раздел «Описание логической структуры» при технологии структурного программирования должен включать следующие материалы:
•	описание связей программы с другими программами;
•	описание внутренних массивов и переменных, которые используются в межмодульном обмене данными;
•	схема иерархии программы (приводится рисунок);
•	расшифровка наименований модулей (приводится таблица с перечнем наименований модулей в алфавитном порядке с указанием выполняемой каждым модулем функции);
•	описание функционирования программы с учетом ее модульного деления (приводится словесное описание выполнения программы с учетом вызовов модулей);
•	описание модулей программы (пораздел заполняется на основе паспортов модулей).
168
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
4.	Раздел «Используемые технические средства» (типы ПК, на которых возможно выполнение программы; устройства, используемые при выполнении программы).
5.	Раздел «Вызов и загрузка» (виды носителей программы, их используемый объем; способы вызова программы с соответствующих носителей данных; входные точки в программу - запуск программы).
6.	Раздел «План мероприятий по разработке и внедрению программы» (план мероприятий разрабатывается для реализации программы коллективом программистов; планом должны быть предусмотрены контрольные временные точки реализации, например, через каждые десять дней или неделю, в течение которых происходит интеграция разработанных модулей и тестирование уже разработанной части программы; приводится состав тестов и принципы их подготовки для тестирования уже созданного фрагмента программы для каждой из контрольных точек).
6.	ТЕХНИКО-ЭКОНОМИЧЕСКИЕ ПОКАЗАТЕЛИ
Технико-экономические показатели должны определяться заказчиком без участия исполнителя.
7.	СТАДИИ И ЭТАПЫ РАЗРАБОТКИ
Разработка программы должна выполняться по следующим этапам:
1)	разработка, согласование и утверждение технического проекта программы с пояснительной запиской - 5 недель;
2)	разработка рабочего проекта программы с комплексным тестированием - 6 недель;
3)	приемка-сдача с исправлением обнаруженных недостатков в программе и программной документации - 2 недели;
4)	внедрение.
8.	ПОРЯДОК КОНТРОЛЯ И ПРИЕМКИ
8.1.	Виды испытаний
Испытания программы и верификация документации должны проводиться в организации заказчика с привлечением сторонних экспертов. Проверочные тесты должны готовиться заказчиком.
8.2.	Общие требования к приемке
Приемка программы должна осуществляться заказчиком. Программа должна считаться годной, если она удовлетворяет всем пунктам данного технического задания.
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
169
2.8.3. Пример технического задания на электронный ресурс
Ниже приведено техническое задание на электронный ресурс «Теория графов и смежные вопросы» (комплект DVD-дисков). Подобный проект выполняется под руководством автора данного пособия. Вся персональная информация, а также название проекта, изменены.
1.	Общие требования к электронному ресурсу
1.1.	Электронный ресурс «Теория графов и смежные вопросы» (теория графов) (далее «электронный ресурс») должен содержать:
1.1.1.	Базу данных, содержащую справочно-библиографическую информацию по темам «комбинаторная оптимизация», «теория графов», применение суперкомпьютерных технологий для решения задач теории графов и комбинаторной оптимизации, структура и характеристики которой приведены в пункте 2.
1.1.2.	Программный продукт, структура и функциональность которого описана в пункте 3.
1.1.3.	Документацию по инсталляции, настройке и эксплуатации электронного ресурса, требования к которой описаны в пункте 5.
2.	Требования к базе данных «теория графов»
2.1.	База данных на момент поставки должна содержать:
2	Д.1. Библиографические описания источников по теме «теория графов».
2.1.2.	URL-ссылки на полные тексты источников по теме «теория графов».
2.1.3.	Систематический каталог по теме «теория графов».
2.1.4.	Новости по теме «теория графов».
2.1.5.	Конференции по теме «теория графов».
2.1.6.	Интернет-ресурсы по теме «теория графов».
2.2.	Состав и структура библиографических описаний источников по теме «теория графов» на момент поставки:
2.2.1.	Библиографическое описание каждого источника должно включать в себя следующую информацию: библиографическая запись (автор, название, выходные данные), оформленная в соответствии с ГОСТ Р 7.0.5-2008;
•	ключевые слова (не^менееГтрех ключевых слов);
•	аннотация;
•	рубрики всех уровней систематического каталога.
170
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.2.2.	Библиографическое описание каждого источника должно быть проверено специалистами в областях дискретной математики и суперкомпьютерных технологий.
2.2.3.	База данных должна содержать библиографические описания не менее 500 источников.
2.2.4.	База данных должна содержать библиографические описания не менее 400 источников, опубликованных за последние десять лет.
2.2.5.	База данных должна содержать библиографические описания не менее 300 источников, опубликованных в предыдущие пять лет.
2.3.	Состав и структура URL-ссылок на полные тексты источников на момент поставки:
2.3.1.	База данных должна содержать не менее 400 актуальных URL-ссылок на полные тексты источников, относящихся к библиографическим описаниям источников «теория графов».
2.3.2.	База данных должна содержать информацию о режиме доступа (свободный или авторизованный) к каждому полному тексту, на которые указывают URL-ссылки.
2.3.3.	Для источников, входящих в коммерческие базы данных, доступ к полным текстам которых организован в локальной сети университета по подписке, URL-ссылки должны указываться в формате, используемом в базах данных (в соответствии с лицензионным договором).
2.3.4.	База данных не должна содержать URL-ссылки на источники, входящие в коммерческие базы данных, доступ к полным текстам которых отсутствует.
2.4.	Систематический каталог по теме «теория графов» должен содержать рубрики трех уровней.
2.4.1.	Систематический каталог на момент поставки должен содержать:
•	не менее 10 заполненных рубрик первого уровня (суммарно);
•	не менее 20 заполненных рубрик второго уровня (суммарно);
•	не менее 60 заполненных рубрик третьего уровня (суммарно).
2.5.	Состав и структура новостей по теме «теория графов» в базе данных на момент поставки.
2.5.1.	Количество записей о новостях должно быть не менее трех.
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
171
2.5.2.	Новость должна представлять собой сообщение о развитии науки и технологий по теме «теория графов» и содержать следующую информацию:
•	заголовок (название);
•	текст новости;
•	URL-ссылка на первоисточник и/или источник дополнительной информации;
•	фамилия, инициалы автора(-ов) новости;
•	дата размещения на электронном ресурсе.
2.5.3.	Новости должны содержать информацию о развитии науки и технологий по теме «теория графов» за период предыдущих 12 месяцев.
2.6.	Состав и структура анонсов конференций по теме «теория графов» в базе данных на момент поставки:
2.6.1.	Количество записей об анонсах конференций должно быть не менее 20.
2.6.2.	Анонс конференции по теме «теория графов» должен содержать следующую информацию:
•	название;
•	место проведения (страна, город);
•	язык конференции;
•	даты проведения;
•	дата подачи заявки (регистрации);
•	дата предоставления тезисов;
•	дата предоставления статей;
•	URL-ссылка на первоисточник и/или источник дополнительной информации.
2.6.3.	Анонсы конференций должны содержать информацию о предстоящих наиболее значимых конференциях по теме применения «теория графов» на период предстоящих 12 месяцев.
2.7.	Состав и структура записей об интернет-ресурсах по теме «теория графов» в базе данных на момент поставки:
2.7.1.	Количество записей об интернет-ресурсах должно быть не менее 30.
2.7.2.	Интернет-ресурс по теме «теория графов» должен содержать следующую информацию:
•	название;
•	актуальная URL-ссылка;
172
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	аннотация.
3.	Требования к программному продукту
3.1.	Программный продукт должен обеспечивать работу следующих сервисов:
3.1.1.	Регистрация, авторизация и администрирование пользователей.
3.1.2.	Электронная библиотека «теория графов».
3.1.3.	Предметный указатель по научной литературе по теме «теория графов».
3.1.4.	Новости о «теории графов».
3.1.5.	Конференции по «теории графов».
3.1.6.	Интернет-ресурсы о «теории графов».
3.1.7.	Новостная рассылка о «теории графов».
3.2.	Требования к сервису «Регистрация, авторизация и администрирование пользователей»
3.2.1.	Сервис «Регистрация, авторизация и администрирование пользователей» должен:
•	обеспечивать ввод информации о пользователях;
•	обеспечивать формирование учетных записей пользователей;
•	обеспечивать управление учетными записями пользователей;
•	обеспечивать идентификацию пользователей при работе с электронным ресурсом;
•	определять для пользователей права доступа к сервисам и функциям электронного ресурса.
3.2.2.	Пользователь электронного ресурса - студент, аспирант, преподаватель, научный сотрудник, который использует электронный ресурс в научных и учебных целях.
3.2.3.	Сервис «Регистрация, авторизация и администрирование пользователей» должен поддерживать следующие группы пользователей.
•	Гость - пользователь, обладающий правами на просмотр библиографического описания источников, новостей, анонсов конференций, интернет-ресурсов.
•	Подписчик - пользователь, обладающий правами на получение новостной рассылки по e-mail.
•	Читатель - пользователь, обладающий правами на просмотр библиографического описания источников и получение доступа к URL-ссылкам на полные тексты источников.
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
173
•	Составитель - пользователь, обладающий правами на добавление в базу данных новых источников.
•	Модератор - пользователь, обладающий правами на проверку источников в базе данных.
•	Администратор - пользователь, обладающий максимальными правами для работы на электронном ресурсе, имеющий право на управление учетными записями пользователей.
3.2.4.	Сервис «Регистрация, авторизация и администрирование пользователей» должен включать в себя следующие функции.
З.2.4.1.	Регистрация пользователей и формирование учетных записей.
Функция регистрации пользователей должна обеспечивать ввод регистрационной информации о пользователе и формирование учетной записи пользователя, которая должна постоянно храниться в базе данных.
Функция регистрации является обязательной для следующих групп пользователей:
•	подписчики;
•	читатели;
•	составители;
•	модераторы;
•	администраторы.
Регистрация пользователя выполняется один раз при первом сеансе работы с электронным ресурсом.
Учетная запись пользователя должна формироваться на основе регистрационной информации о пользователе и должна включать в себя следующую информацию:
•	фамилия, имя, отчество;
•	e-mail;
•	контактная информация;
•	логин (имя пользователя на электронном ресурсе);
•	пароль.
При регистрации пользователя на электронном ресурсе обязательным для заполнения должны быть следующие поля: логин; пароль; e-mail.
Для пользователей, входящих в группы составители, модераторы, администраторы, обязательным для заполнения при регистрации яв
174
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
ляются следующие поля: фамилия; имя; отчество; e-mail; контактная информация; логин; пароль.
3.2.4.2.	Авторизация пользователей.
Функция авторизации пользователей должна заключаться во вводе имени пользователя (логина) и пароля, указанных при регистрации, при котором должна происходить идентификация пользователей и подтверждение прав пользователей на использование функций и выполнение операций.
Функция авторизации является обязательной для следующих групп пользователей:
•	читатели;
•	составители;
•	модераторы;
•	администраторы.
3.2.4.3.	Администрирование пользователей.
Функция администрирования пользователей должна обеспечивать возможность выполнения операций над учетными записями пользователей.
3.2.5.	Сервис «Регистрация, авторизация и администрирование пользователей» должен включать в себя следующие операции:
3.2.5.1.	Просмотр списка учетных записей пользователей.
3.2.5.2.	Выбор учетной записи пользователя для редактирования регистрационной информации.
3.3.	Требования к сервису «Электронная библиотека «теория графов»
3.3.1.	Сервис «Электронная библиотека» должен предоставлять доступ к базе данных источников по теме «теория графов».
3.3.1.1,	В «Электронной библиотеке» доступ к источникам должен быть организован посредством выбора типов источников: «Научные статьи», «Труды конференций», «Книги», «Электронные ресурсы». Для каждого типа источника должен быть доступен алфавитный указатель на источники.
3.3.2.	Сервис «Электронная библиотека» должен включать в себя следующие функции:
3.3.2.1.	Просмотр списка источников.
3.3.2.2.	Просмотр библиографического описания источника, структура которого описана в пункте 2.2.1.
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
175
3.3.2.3.	Доступ к URL-ссылке на полный текст источника (опционально, при наличии полного текста и наличии у пользователя соответствующих прав доступа).
3-3.2.4. Поиск источника. Поиск источника должен осуществляться по следующим параметрам:
•	код источника;
•	автор;
•	название;
•	ключевые слова.
3.3.2.5.	Генерация библиографических ссылок по ГОСТ Р 7.0.5-2008.
3.3.3.	Сервис «Электронная библиотека» должен включать в себя следующие операции.
З.З.З.1.	Добавление библиографического описания нового источника в базу данных. Заполнение всех полей должно быть обязательным.
3.3.3.2.	Отправка замечаний «Модератору». Информирование «Модератора» (автоматически посредством e-mail) о добавлении источника в базу данных. В тексте письма должна присутствовать следующая информация:
•	дата добавления источника в базу данных;
•	фамилия, имя, отчество «Составителя», который добавил этот источник в базу данных;
•	полное содержание библиографического описания с указанием имен полей и значений;
•	URL-ссылка на источник.
З.З.З.З.	Просмотр списка новых записей об источниках.
3.3.3.4.	Выбор и просмотр источника для проверки.
3.3.3.5.	Публикация источника на электронном ресурсе.
3.3.3.6.	Отправка замечаний «Составителю». Информирование «Составителя» (автоматически посредством e-mail) об проверке источника.
3.4-	Требования к сервису «Предметный указатель по научной литературе» по теме «теория графов»
3.4.1.	Сервис «Предметный указатель по научной литературе» по теме «комбинаторная оптимизация» должен обеспечивать возможность создания и редактирования предметных рубрик трех уровней
систематического каталога и поиск источников.
176
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
3.4.2.	Сервис < Предметный указатель по научной литературе» должен включать в себя следующие функции.
З.4.2.1.	Просмотр списка рубрик первого уровня.
3.4.2.2.	Выбор рубрики первого уровня.
3.4.2.3.	Просмотр списка рубрик второго уровня.
3.4.2.4.	Выбор рубрики второго уровня.
3.4.2.5.	Просмотр списка рубрик третьего уровня.
3.4.2.6.	Выбор рубрики третьего уровня.
3.4.2.7.	Формирование списка ссылок для рубрик любого уровня. Список ссылок должен иметь следующую структуру:
•	код источника;
•	авторы;
•	название;
•	URL-ссылка на библиографическое описание источника.
3.4.2.8.	Поиск источников, который должен осуществляться по рубрикам систематического каталога.
3.4.3.	Сервис < Предметный указатель по научной литературе» должен включать в себя следующие операции.
3.4.3.1.	Добавление рубрики первого уровня систематического каталога в базу данных. Рубрика первого уровня должна содержать следующие элементы: название (обязательно для заполнения); комментарий (необязательно для заполнения).
3.4.3.2.	Добавление рубрики второго уровня систематического каталога в базу данных. Для добавления рубрики второго уровня необходимо: выбрать рубрику первого уровня; ввести название рубрики второго уровня (обязательно для заполнения); ввести комментарий (необязательно для заполнения).
3.4.3.3.	Добавление рубрики третьего уровня систематического каталога в базу данных. Для добавления рубрики третьего уровня необходимо: выбрать рубрику второго уровня; ввести название рубрики третьего уровня (обязательно для заполнения); ввести комментарий (необязательно для заполнения).
3.5.	Требования к сервису «Новости в области теории графов»
3.5.1.	Сервис < Новости в области теории графов» должен предоставлять доступ к новостям о науке и технологиях по теме применения СКТ при решении задач теории графов, размещенным на электронном ресурсе.
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
177
3.5.2.	Сервис «Новости» должен включать в себя следующие функции.
З.5.2.1.	Просмотр списка новостей за определенный период времени. Список новостей должен быть организован в хронологическом порядке.
3.5.2.2.	Просмотр новости. Содержание новости должно соответствовать пункту 2.5.2.
3.5.3.	Сервис «Новости» должен включать в себя следующие операции.
З.5.З.1.	Добавление новости в базу данных.
3.5.3.2.	Отправка замечаний «Модератору». Информирование «Модератора» (автоматически посредством e-mail) о добавлении новости в базу данных. В тексте письма должна присутствовать следующая информация:
•	дата добавления новости;
•	фамилия, имя, отчество «Составителя», который добавил новость;
•	полная информация о новости, согласно пункту 2.5.2;
•	URL-ссылка на новость.
3.5.3.3.	Просмотр списка новых записей о новостях.
3.5.3.4.	Выбор и просмотр новости для проверки.
3.5.3.5.	Проверка новости.
3.5.3.6.	Отправка замечаний «Составителю». Информирование составителя (автоматически посредством e-mail) о проверке новости.
3.6.	Требования к сервису «Конференции в области теории графов»
3.6.1.	Сервис «Конференции в области теории графов» должен предоставлять доступ к анонсам конференций, размещенным на электронном ресурсе.
3.6.2.	Сервис «Конференции» должен включать в себя следующие функции.
З.6.2.1.	Просмотр списка анонсов конференций за произвольный период времени. Анонсы конференций должны быть организованы в хронологическом порядке.
3.6.2.2.	Просмотр анонса конференции. Содержание анонса конференции должно соответствовать пункту 2.6.2.
3.6.3.	Сервис «Конференции» должен включать в себя следующие операции.
178
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
З.6.З.1.	Добавление анонса конференций в базу данных.
3.6.3.2.	Отправка замечаний «Модератору». Информирование «Модератора» (автоматически посредством e-mail) об анонсе конференции в базу данных. В тексте письма должна присутствовать следующая информация:
•	дата добавления анонса конференции;
•	фамилия, имя, отчество составителя, который добавил анонс конференции;
•	полная информация об анонсе конференции, согласно пункту 2.6.2;
•	URL-ссылка на анонс конференции.
3.6.3.3.	Просмотр списка новых записей об анонсах конференций.
3.6.3.4.	Выбор и просмотр анонса конференции для проверки.
3.6.3.5.	Проверка анонса конференции.
3.6.3.6.	Отправка замечаний «Составителю». Информирование «Составителя» (автоматически посредством e-mail) о проверке анонса конференции.
3.7.	Требования к сервису «Интернет-ресурсы о теории графов»
3.7.1.	Сервис «Интернет-ресурсы о теории графов» должен предоставлять доступ к информации об интернет-ресурсах по теме применения суперкомпьютерных технологий при решении задач теории графов.
3.7.2.	Сервис «Интернет-ресурсы» должен включать в себя следующие функции.
3.7.2.1.	Просмотр списка интернет-ресурсов, который должен быть организован в виде тематических рубрик.
3.7.2.2.	Просмотр информации об интернет-ресурсе. Содержание информации об интернет-ресурсе должно соответствовать пункту 2.7.2.
3.7.3.	Сервис «Интернет-ресурсы» должен включать в себя следующие операции.
3.7.3.1.	Добавление информации об интернет-ресурсе в базу данных.
3.7.3.2.	Отправка замечаний «Модератору». Информирование «Модератора» (автоматически посредством e-mail) о добавлении интернет-ресурса в базу данных. В тексте письма должна присутствовать следующая информация:
•	дата добавления интернет-ресурса;
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
179
•	фамилия, имя, отчество «Составителя», который добавил интернет-ресурс;
•	полная информация об интернет-ресурсе, согласно пункту 2.7.2;
•	URL-ссылка на интернет-ресурс.
3.7.3.3.	Просмотр списка новых записей о интернет-ресурсах.
3.7.3.4.	Выбор и просмотр информации о интернет-ресурсе для про верки.
3.7.3.5.	Проверка информации об интернет-ресурсе.
3.7.3.6.	Отправка замечаний «Составителю». Информирование «Составителя» (автоматически посредством e-mail) о проверке интернет-ресурса.
3.8.	Требования к сервису «Новостная рассылка о теории графов»
3.8.1.	Сервис «Новостная рассылка о теории графов» должен предоставлять доступ к оформлению подписки на новостную рассылку и получению сообщений по e-mail о новой информации на электронном ресурсе.
З.8.1.1.	В текст сообщения «Новостной рассылки» должна быть включена следующая информация: новинки «Электронной библиотеки», новые рубрики «Предметного указателя по научной литературе» по теме «теория графов», новости «теория графов», анонсы конференций «теория графов», интернет-ресурсы «теория графов».
3.8.2.	Сервис «Новостная рассылка» должен включать в себя следующие функции.
З.8.2.1.	Подписка на новостную рассылку. Подписка на новостную рассылку должна состоять из регистрации на электронном ресурсе (для пользователей, которые ранее не регистрировались) и подтверждения согласия на получение новостной рассылки по e-mail. При оформлении подписки на новостную рассылку пользователь автоматически заносится в группу «Подписчики».
3.8.2.2.	Отказ от получения новостной рассылки.
3.8.3.	Сервис «Новостная рассылка» должен включать в себя следующие операции.
3.8.3.1.	Автоматическая генерация текста сообщений новостной рассылки за произвольно-выбранный период времени. Операция генерации текста сообщений должна осуществляться пользователем, входящим в группу «Модераторы».
3.8.3.2.	Рассылка текста сообщений новостной рассылки по e-mail. Периодичность рассылки должна быть конфигурируемой опцией. Ва
180
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
рианты выбора периодичности рассылки должны быть следующие: один раз в неделю; два раза в месяц; один раз в месяц.
4.	Технические требования к аппаратно-программной платформе для размещения электронного ресурса
4.1.	Все функции по управлению и доступу к электронному ресурсу должны быть реализованы через веб-интерфейс.
4.2.	Электронный ресурс должен устойчиво функционировать на аппаратно-программной платформе, которая имеет следующие характеристики:
4.2.1.	Процессор с техническими параметрами не ниже Intel Core 2 Duo.
4.2.2.	Объем оперативной памяти не менее 2 гигабайт.
4.2.3.	Свободное пространство на жестком диске не менее 20 гигабайт.
4.2.4.	Доступ в сеть интернет со скоростью не менее 256 Кбит/с.
4.2.5.	Операционная система семейства Windows Server.
4.2.6.	Система управления базами данных MySQL 5.0.
4.2.7.	Интернет-сервер Apache 2.0.
4.2.8.	Интерпретатор языка PHP 5.0.
5.	Требования к документации по электронному ресурсу
5.1.	Документация по электронному ресурсу «теория графов» должна содержать следующую информацию.
5.1.1.	Инструкция по инсталляции и настройке электронного ресурса «теория графов», которая должна содержать сведения:
•	о требованиях к аппаратной и программной платформах;
•	об этапах инсталляции;
•	об этапах соединения с системой управления базами данных.
5.1.2.	Инструкция по эксплуатации электронного ресурса «теория графов», которая должна содержать подробные сведения о порядке и правилах работы, основных функциях и операциях при работе всех групп пользователей с электронным ресурсом.
5.2.	Каждая инструкция должна быть оформлена в виде отдельного файла и должна иметь формат документа Microsoft Word (версия 2003 и выше).
6.	Начальная цена контракта: N тысяч рублей.
7.	Порядок поставки товаров.
Место поставок товара - юридический адрес организации.
2.8. ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПРОЕКТИРОВАНИЕ
181
F »1ЛЫ fai flay*, ><му<н;и№ S frvMtTpfriHvH? Г-О'УОС* L' .«урн.зпы
СЗЖИ	&>ММГН^ЛЯИвИ» tSKUB	ИвЖЮОДвШ	Пмо<о«Тт»н.*н«тол
J Электронная библиотека
Ч Поиск источнику
+ МШВыКЗде?
ЗМиом игочниы (25)
Научные статьи
1	b-onj
Tatyana Pankova Chain Sequences with Ordered Endosing tt Pleiades Publishing. Ltd (Ппеадос Пабпишинг.
Птд). 2007 Vol 46. No 1 P 83-92
Ключевые слова: планарный граф. цепь, упорядоченное охватывание. алгоритм
Tatyana Panyukova Eutenan Cover with Ordered Endosing lor Ret Graphs U Electrode Notes in Dscrete Mathemrtcs. 2007 Vol 28 P 17-24
Ключевые слова: Эйлеров граф. цель. i*em. путь, алгоритмы, упорядоченюе охватывание Полны*
э е+ччн^м^	to Wr w fir*fr тиг«*гг	a
Vafcakhmetwe J.I Hyper-Heunsac Algorithms in Modem Search Technology (Гиперэвристичесине алгоритмы e современной теории поиска) И Proceedings oh the 13-th Irtemebonai Workshop on Computer Science and Wormation Technologies, издательство УГАТУ. 2011 Vol 1.P 208-211
Ключевые слова: гмперэеристмм. метаэврмстжи. генепыесмю алгоритмы
Рис. 2.1. Внешний вид библиотеки «Теория графов»
Сроки (периоды) поставок товара - не более 30 дней после заключения государственного контракта.
8. Расчеты по государственному контракту.
Форма оплаты товаров - в безналичной форме.
Условия и сроки оплаты товаров - в объеме 100% цены контракта до 31 декабря календарного года, в котором приобретался электронный ресурс, после передачи товаров представителю Заказчика и подписания акта приема-сдачи выполненных работ.
Внешний вид готового продукта приведен на рис.2.1.
182
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
2.9.	Эскизный, технический, рабочий проект программного средства
Сделаем любой проект быстро, качественно, дешево -выбирайте любые два условия.
(Народная мудрость)
Результатом проектирования обычно является «Эскизный проект» (Software Design Document) или «Технический проект» (Software Architecture Document). Эти документы содержат помимо перечисленных материалов принципиальные электрические схемы и конструкторскую документацию объекта разработки и составных его частей, перечень выбранных готовых средств программного и технического обеспечения (в том числе - ЭВМ, операционной системы , прикладных программ и т.д.), а также алгоритмы решения задач для разработки новых средств программного обеспечения и др.
Технический проект - стадия разработки конструкторской документации на изделие или стадия создания автоматизированной системы.
В более узком смысле под техническим проектом понимается совокупность технических документов, которые содержат окончательные проектные решения по изделию (системе) и исходные данные для разработки рабочей документации.
После согласования и утверждения в установленном порядке технический проект служит основанием для разработки рабочей документации. Последовательность выполнения всех стадий составляет процесс проектирования.
Разработку технического проекта на материальные изделия осуществляют в соответствии с Единой системой программной документации (ЕСПД), на автоматизированные системы - в соответствии с Комплексом стандартов на автоматизированные системы.
Согласно ЕСПД (ГОСТ 19.102-77) стадия «Эскизный проект» состоит из следующих этапов.
Разработка эскизного проекта - на этом этапе выполняются [10]:
•	предварительная разработка структуры входных и выходных данных.
2.9. ПРОЕКТЫ ПРОГРАММНОГО СРЕДСТВА
183
•	уточнение методов решения задачи;
•	разработка общего описания алгоритма решения задачи;
•	разработка технико-экономического обоснования.
Утверждение эскизного проекта - на этом этапе выполняются:
•	разработка пояснительной записки;
•	согласование и утверждение эскизного проекта.
Таким образом, на стадии разработки эскизного проекта детально разрабатываются структуры входных и выходных данных, определяется форма их представления. Разрабатывается общее описание алгоритма, сам алгоритм, структура программы. Разрабатываются план мероприятий по разработке и внедрению программы.
Стадия «Технический проект» состоит из следующих этапов [101-
На этапе «Разработка технического проекта» выполняются:
•	уточнение структуры входных и выходных данных;
•	разработка алгоритма решения задачи;
•	определение формы представления входных и выходных данных;
•	определение семантики и синтаксиса языка;
•	разработка структуры программы;
•	окончательное определение конфигурации технических средств.
На этапе «Утверждение технического проекта» выполняются:
•	разработка плана мероприятий по разработке и внедрению программы;
•	разработка пояснительной записки;
•	согласование и утверждение технического проекта.
Следовательно, технический проект содержит разработанный алгоритм решения задачи, а также методы контроля исходной информации. Здесь же разрабатываются средства обработки ошибок и выдачи диагностических сообщений, определяются формы представления исходных данных и конфигурация технических средств.
Рабочее проектирование - заключительная стадия проектирования, которая помимо требуемой ГОСТ 34.601-90 разработки рабочей документации на систему и ее части в общем случае предусматривает уточнение и детализацию результатов предыдущих этапов, создание и испытания опытного и/или опытно-промышленного образца объекта автоматизации, разработку и отработку программных продуктов, технологической и эксплуатационной документации. Результаты излагаются в рабочем или технорабочем проекте. В современной практике
184
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
проектирования автоматизированных информационных систем он является начальным этапом их внедрения в работу фирмы, организации или службы, являющейся заказчиком проекта, или головной в ряде других автоматизируемых фирм, организаций, служб и т.д.
Стадия «Рабочий проект» состоит из следующих этапов [10].
На этапе «Разработка программы» осуществляется программирование и отладка программы.
На этапе «Разработка программной документации» выполняется разработка программных документов в соответствии с требованиями ЕСПД.
На этапе «Испытания программы» происходит:
•	разработка согласование и утверждение программы и методики испытаний;
•	проведение предварительных государственных, межведомственных, приемо-сдаточных и других видов испытаний;
•	корректировка программы и программной документации по результатам испытаний.
На стадии создания рабочего проекта осуществляется программирование и отладка программы, разработка программных документов, программы и методики испытаний. Подготавливаются контрольно-отладочные примеры. Окончательно оформляются документация и графический материал. Обычно указывается, что в ходе разработки программы должна быть подготовлена следующая документация:
•	текст программы;
•	описание программы;
•	программа и методика испытаний;
•	описание применения;
•	руководство пользователя.
Это стандартные требования, если заказчик соглашается с тем, что можно не представлять весь этот список, то это означает несерьезность его намерений в отношении компании и выпускаемого ею продукта. Единственное, что может отсутствовать - это графический материал. Но для серьезных проектов этот пункт обязателен.
2.10. ДОКУМЕНТАЦИЯ ТЕСТИРОВАНИЯ
185
2.10.	Документация тестирования компонентов и комплексов программ
Программы без ошибок можно написать двумя способами, но работает третий.
(Алан Дж.Перлис)
Документация тестирования ПО осуществляется по международному стандарту IEEE 829. Российского аналога на данный момент не существует, и технические писатели пользуются англоязычным стандартом, либо ищут переводные версии данного документа. Это базовый стандарт, описывающий вспомогательные артефакты тестирования. Написанные в соответствии с ним документы получаются короткими, простыми, понятными и практичными. Основными такими артефактами являются следующие [13].
Тестовый план (test plan) - основной документ, связывающий разработку тестов и тестирование с задачами проекта. Определяет необходимые в проекте виды тестирования, используемые техники, проверяемые характеристики, компоненты системы, подлежащие тестированию, критерии оценки полноты тестов и критерии завершения тестирования на различных этапах, а также план выполнения отдельных действий по подготовке и проведению тестов и привязку ресурсов для этого. Тестовый план проекта должен корректироваться в соответствии с текущими задачами и рисками проекта, а также с появляющимися данными о качестве отельных составляющих системы.
Тестовые варианты (test case) - сценарии проведения отдельных тестов. Каждый тестовый вариант предназначен для проверки определенных свойств некоторых компонентов системы в определенной конфигурации и включает:
•	действия по инициализации тестируемой системы (или компонента);
•	приведение ее в необходимое состояние, вместе с предыдущим шагом составляет преамбулу тестового варианта;
•	набор воздействий на систему, выполнение которых должно быть проверено данным тестом;
•	действия по проверке корректности поведения системы - сравнение полученных и ожидаемых результатов, проверка необходи
186
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
мых свойств результатов, проверка инвариантов данных системы и пр.;
•	финализацию системы - освобождение захваченных при выполнении теста ресурсов.
Переведем основные положения стандарта IEEE 829 «Шаблон документации тестирования ПС» [42].
Определение тестового плана
Пусть некоторые компании уже воспользовались разработанным тестовым планом, оценили его уровень и определили уровень ПО, для которого используется данный документ.
Очевидно, тестовый план будет иметь тот же уровень, что и соответствующее ему программное обеспечение. Можно определить, является ли план испытаний генеральным, планом определенного уровня, планом интеграции или любой другой разновидностью представленных планов. Это также содействует координации программ и тестовых версий при управлении конфигурациями.
Следует иметь в виду, что тестовые планы, как и прочая документация программного обеспечения, динамичны по своей природе и должны всегда находиться в актуальном состоянии. Таким образом, им должны быть присвоены т.н. номера ревизий.
В тестовые планы можно включить информацию об авторе и контактную информацию, включая информацию о пересмотре части тестов.
Ссылки
Данный раздел содержит перечисление всех документов, присутствующих в тестовом плане. Он ссылается на актуальную версию сохраненного в системе управления версиями документа. Не следует досконально копировать в этот раздел текстовые фрагменты из других частей документа, т.к. это резко снижает жизнеспособность документа и повышает накладные расходы. Необходимо только перечислить следующие документы:
•	план проекта;
•	требования к спецификациям;
•	документ оформления высокого уровня;
•	документ оформления детальный;
•	стандарты на разработку и тестирование;
•	руководства по методологии и примеры;
•	корпоративные стандарты и руководства.
2.10. ДОКУМЕНТАЦИЯ ТЕСТИРОВАНИЯ
187
Введение
Указать предназначение тестового плана и, при необходимости, уровень предоставляемого плана. Это особенно важно для исполнительной части плана.
Можно включать любые ссылки на другие планы, документы или положения, содержащие близкую к тематике проекта/процесса информацию. Лучше всего создать раздел со ссылками на все сопутствующие документы.
Определить обзорный план по отношению к плану программного проекта. Другие элементы плана могут включать перечисление ресурсов и бюджетных ограничений, объем работ по тестированию. Здесь же отмечается, каким образом тестирование относится к другим видам процесса оценки (анализ и обзоры), и перечисляются прочие возможные процессы, которые будут использоваться для контроля за изменениями, связями и координацией основных мероприятий.
Тестируемые объекты (функциональность)
Здесь приводятся позиции, которые тестируются в рамках общего тестового плана, т.е. приводится полный список всего, что планируется протестировать. Этот список можно составить на основе описания программы и прочих подобных средств получения информации о программе.
Процесс может быть контролируемым, определяемым локальным процессом управления конфигурацией, если такой имеется. Данная информация включает номер версии, требования к конфигурации (при необходимости, если поддерживается несколько версий продукта). Процесс может также включать основные вопросы, график поставки для критических элементов.
Следует помнить, тестируется то, что впоследствии предполагается донести до клиента. Содержание данного раздела очень сильно зависит от уровня тестового плана. Для высших уровней здесь могут содержаться тесты для приложения в целом либо области функционирования, для более низших - для программы, блока, модуля, надстройки.
Факторы риска определяют, какое программное обеспечение предполагается протестировать и найти критические точки, например:
•	поставка сторонних продуктов;
•	новая версия интерфейса;
188
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	возможность использования и понимания новой поставки/инструмента и т.д.
•	чрезвычайно сложные функции;
•	изменение компонент, в истории которых отмечены сбои;
•	плохо документированные модули или запросы на изменения.
Более того, должны быть определены некоторые риски в работе программного обеспечения, такие как сложности в:
•	безопасности;
•	множественных интерфейсах;
•	воздействии на клиента;
•	законодательстве и правилах.
Еще одной зоной риска является недопонимание первичных требований. Ошибки в этой области могут возникнуть на уровнях управления, пользовательском уровне, либо на уровне разработки. Следует иметь в виду и неопределенные либо неясные требования, которые не могут быть проверены.
Устаревшие списки ошибок, обнаруженные при модульном тестировании, помогут выявить потенциальные опасные области в рамках программного обеспечения. Если при модульном тестировании обнаружено большое количество ошибок, значит имеет место некоторая ошибочная тенденция в определенной области программного обеспечения. Это является показателем потенциальных проблем при будущем тестировании и природой дефектов. Существует единственный хороший подход для определения наличия рисков: мозговой штурм.
Тестируемые опции - список действий системы, которые должны быть проверены с пользовательской точки зрения. Это не техническое описание программного обеспечения, а пользовательский взгляд на функции.
Необходимо установить степень риска для каждой функции. Для этого используется простая рейтинговая шкала, такая как (Н, М, L): высокий (high), средний (medium) и низкий (low). Подобное подразделение на уровни понятно пользователю. Следует обосновывать выбор конкретного уровня.
Не тестируемые опции
В данном разделе приводится список всего, что не должно быть протестировано ни с точки зрения пользователя системы, ни со стороны системы управления конфигурацией. Это не техническое описание
2.10. ДОКУМЕНТАЦИЯ ТЕСТИРОВАНИЯ
189
программного обеспечения, а только пользовательский взгляд на ее функциональность.
Необходимо определить, почему не требуется тестирование тех или иных компонент. На это может быть множество причин:
•	программа не включается в релиз текущей версии программы;
•	низкий риск получения ошибки;
•	не планируется выпускать или тестировать или документировать часть релиза данной версии программного продукта.
Описание подхода (стратегии) - это индивидуальный подход к тестовому плану; он должен соответствовать уровню всего тестового плана (мастер, приемка, и т.д.) и должен входить в соглашение со всеми высшими и низшими уровнями плана. Должны быть определены общие правила и процессы, в том числе требуется ответить на вопросы.
•	Должен ли использоваться какой-либо специальный инструментарий и какой именно?
•	Требует ли этот инструментарий дополнительного обучения?
•	Какие метрики будут контролироваться?
•	На каком уровне контролируется каждая из метрик?
•	Каким образом осуществляется управление конфигурацией?
•	Сколько различных конфигураций предполагается тестировать?
•	Какое аппаратное и программное обеспечение используется?
•	Каким образом осуществляется совместное использование аппаратного и программного обеспечения и прочих пакетов?
•	Какие уровни регрессионного тестирования будут пройдены и как много тестов проводится на каждом уровне?
•	Будет ли регрессионное тестирование основано на серьезности обнаруженных дефектов?
•	Каким образом будут обработаны элементы требований и бессмысленное оформление?
Если данный тестовый план является основным планом проекта обязательно необходимо определить и общее тестирование проекта. Стоит указать имеются ли специальные требования для тестирования.
Должны быть протестированы только завершенные, полные компоненты. Специальные сегменты группировки свойств/компонент тестируются совместно.
190
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Критерии прохождения/провала тестовых заданий
Определим критерии завершения тестового плана. Они являются критическим аспектом любого плана и должны соответствовать его уровню.
На уровне тестирования модулей необходимо определить следующее:
•	рассмотреть все случаи тестирования;
•	определенное количество завершенных тестов, имеющих минимальные дефекты;
•	инструмент, указывающий на покрытие тестами всего кода.
На профессиональном уровне могут быть протестированы следующие компоненты:
•	завершены все планы более низких уровней;
•	определенное число планов, завершенных с минимумом дефектов.
Далее можно выделить индивидуальный критерий для определения уровня тестов либо указать функциональные требования для планов более высокого уровня и определить число и серьезность выявленных дефектов, а заодно и возможность сравнить число выявленных на данном уровне дефектов с общим числом дефектов. Может оказаться, что данную процедуру не удается выполнить в силу невозможности определения некоторых дефектов.
Под дефектом понимается процесс, который может привести к некорректной работе программы, но его допускается оставить в приложении.
Ошибкой называется результат неверного выполнения программы, видимый пользователю, в системных кэшах и т.д.
Критерии приостановления/возобновления работы
Необходимо знать, когда стоит приостановить серию тестов.
Если число или вид дефектов достигает критической точки, когда процесс тестирования уже не имеет никакого смысла, не стоит дальше продолжать тестирование, это приведет только к потере ресурсов.
Указать, что является причиной краха теста или серии тестов, и каков допустимый уровень дефектов для продолжения процесса тестирования.
В результате тестирования при проявлении критической ошибки следует вывести список дефектов. Фактически они будут обобщать ранее выявленные, но проигнорированные дефекты.
2.10. ДОКУМЕНТАЦИЯ ТЕСТИРОВАНИЯ
191
Итоги тестирования
Частью этого плана может быть получено:
•	документация плана тестирования;
•	тестовые случаи;
•	спецификации оформления тестов;
•	инструментарий и выходные данные;
•	симуляторы;
•	статические и динамические генераторы;
•	журналы ошибок и выполнения;
•	сообщения о проблемах и корректировочные действия.
Единственное, что не удается получить с помощью тестов, это само тестируемое программное обеспечение.
Оставшиеся тестовые задания
Если имеется в виду многофазный процесс либо заявка выпускается с некоторым шагом по времени, то могут возникнуть части приложения, к которым данный план не имеет никакого отношения. Необходимо определить такие области, чтобы избежать каких-либо неопределенностей по отношению к дефектам. Это также позволит пользователям и тестерам избежать работы с недоработанными функциями и предотвратить нерациональное использование не дефектных ресурсов.
Если проект разрабатывается как сложный процесс, этот план может охватывать только часть общих функций/возможностей. Это состояние должно быть идентифицировано так, что области имеют планы, разработанные для них, чтобы сэкономить ресурсы отслеживания дефектов, не относящиеся к этому плану.
Когда третья сторона разрабатывает программное обеспечение, в данном разделе могут содержаться описания тестовых заданий, принадлежащих к обеим группам внутренних и внешних групп.
Потребности среды
Существует ряд специальных требований к тестовому плану, например:
•	специальное аппаратное обеспечение, такое как симуляторы, статические генераторы и т.д.;
•	способ ввода тестовых данных; специальные требования, диапазон ввода тестовых данных;
•	особенности и продолжительность тестирования для каждого отдельного компонента;
•	требования к мощности оборудования;
192
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	требования к прочему дополнительному программному обеспечению;
•	использование системы в течение процесса тестирования.
Проблемы кадров и обучения
В этом разделе фиксируются особенности обучения работе с при-ложением/системой и обучения всем ее возможностям. Определяется, что предполагается тестировать и кто ответственен за тестирование и обучение.
Ответственность
Данный раздел включает в себя все аспекты плана, например:
•	риски;
•	выбор объектов для тестирования;
•	определение общей стратегии для текущего уровня плана;
•	обеспечение выполнения всех элементов тестирования;
•	обеспечение разрешения конфликтов планирования, особенно, когда тестирование проводится в производственной системе;
•	определение лица, проводящего обучение системы;
•	указание лица, отвечающего за решения проведения/не проведения тестирования для отдельных элементов плана.
Расписание должно основываться на реальных проверенных данных. Если полученные данные, на которые опирается работа приложения, не верны, то и весь тестовый план будет не надежен.
Как известно, в первую очередь тестируется сам план проекта. Данная задача обычно сводится к решению проблемы «Давайте сделаем хотя бы что-нибудь, даже если он действительно не так хорошо работает, как хотелось бы». Конечно, такое решение является самым неподходящим. Здесь же указывается, каким образом избежать проскальзывания в расписании.
Если пользователи знают заранее, что отставание в развитии проекта является следствием проскальзывания в тесте и общей деятельности системы, им придется быть немного более терпимыми. Потому что данный процесс проводится в их интересах с целью повышения качества тестируемого приложения.
Теоретически можно обсудить возможные дефекты до их фактического возникновения. Даже можно предложить пользователям принять программу с несколькими дефектами в случае работы по скользящему графику.
2.10. ДОКУМЕНТАЦИЯ ТЕСТИРОВАНИЯ
193
На данном этапе, все соответствующие вехи следует тесно связывать с процессом развития. Это также поможет в выявлении и отслеживании потенциального проскальзывания в расписании из-за проведения тестирования.
Такое поведение системы всегда лучше, ведь это позволяет непосредственно связать все тестовые и активные данные. Благодаря этому тест команда не воспринимается причиной задержки. Например, если тестирование системы начнется после сдачи окончательной сборки, то система тестирования начинает свою работу непосредственно после запуска. Если выпуск программы задерживается, системное тестирование начинается со дня поставки, а не в запланированный день. Это называется зависимым или относительным датированием.
Планирование рисков и непредвиденных обстоятельств
Суммарные риски по проекту включают в себя:
•	отсутствие кадровых ресурсов при тестировании;
•	отсутствие необходимого оборудования, программного обеспечения, данных и инструментов;
•	поздняя доставка программного обеспечения, оборудования и инструментов;
•	задержки в обучении применению и/или использованию инструментария;
•	изменение первоначальных требований или оформления.
Необходимо указать, что будет сделано для проведения различных мероприятий, например, «определение требований будет завершено к 1 января N-ro года, и, в случае изменения требований после этой даты, будут приняты следующие меры».
График тестирования и разработки графика должен выйти в через фиксированное число дней. Такое встречается редко, так как большинство проектов, как правило, имеют фиксированные сроки поставки.
Следующие два момента могут привести к снижению общего качества поставляемой продукции:
•	количество проводимых тестов подлежит сокращению;
•	количество допустимых дефектов будет увеличено.
Кроме того,
•	ресурсы могут добавляться тестовой командой;
•	группа тестирования будут работать сверхурочно (это может повлиять на моральное состояние команды);
•	общий план может быть изменен;
194
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	может быть выполнена некоторая оптимизация использования ресурсов. По возможности этого следует избегать;
•	с точки зрения управления, как правило, неохотно принимаются такие сценарии, как было описано выше, даже если основываться на прошлом опыте.
Важно помнить, что если вообще ничего не делать, то тестирование естественным образом будет сокращено или опущено полностью. Но все это не допустимо!
Утверждения
Необходимо ответить на вопрос: кто вправе определить процесс тестирования как завершенный и позволит проекту перейти на следующий уровень (в зависимости от уровня плана)?
Например, в плане уровня испытаний ими могут выступать все заинтересованные стороны.
При определении процесса подтверждения, следует иметь в виду целевую аудиторию программного продукта.
Аудитория на уровне плана модульного тестирования отличается от аудитории плана уровня интеграции, системы или мастерского уровня.
Величина и типы знаний на различных уровнях могут отличаться.
Программисты очень техничны, но могут не иметь четкого представления о бизнес-процессах выполнения проекта.
Пользователи, например, имеют различные уровни деловой активности и им может недоставать технических навыков.
Всегда следует с особой осторожностью общаться с пользователями, которые утверждают, будто имеют высокий уровень технических навыков, и программистами, которые считают, что в состоянии полностью понять бизнес-процесс. Эти типы людей могут причинить больше вреда, чем пользы, если они не владеют навыками, которыми (как они наивно считают) они обладают в полной мере.
2.11. ДОКУМЕНТАЦИЯ СОПРОВЖДЕНИЯ
195
2.11.	Документация сопровождения и конфигурационного управления версиями программ
Бог смог сотворить мир всего за шесть дней только потому, что ему не надо решать проблемы совместимости с предыдущими версиями.
(Неизвестный автор)
Данный вопрос очень подробно освещен в [12]. Ниже, если не оговорено иное, приведенный материал позаимствован из этого источника.
На крупных промышленных предприятиях, в магазинах, книжных издательствах и в прочих организациях существуют склады. Основная задача склада - обеспечить хранение и доступ к материальным активам: товарам, изделиям, книгам и пр. То есть различных материальных активов становится настолько много, что необходима специальная служба по их учету.
Рассмотрим теперь проект по разработке программного обеспечения. Учета и контроля, сродни складскому, требуют и файлы проекта. В программном проекте их число может достигать сотен и тысяч даже для относительно небольших проектов. Создать новый файл очень легко. Многие технологии программирования поддерживают стиль, когда, например, для каждого класса создается отдельный файл.
Под файлом будем понимать виртуальную информационную единицу. Главное отличие файла от материальных единиц учета заключается в том, что у файла может быть версия, и не одна, и породить эти версии очень легко - достаточно скопировать данный файл в другое место на диске. В то время как материальные предметы существуют на складе сами по себе, и для них нет понятия версии. Может быть несколько однотипных предметов, разных заготовок изделия различной степени готовности. Версия файла - это очень непростой объект. Одна версия отличается от другой несколькими строками текста или полностью обновленным содержанием. Возникает вопрос: какая из двух и более версий главнее, лучше? К этому добавляется еще и то, что многие рабочие продукты могут состоять из набора файлов, и каждый из них может иметь несколько версий.
196
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
В итоге в программном проекте начинают происходить следующие события:
•	тщательно оттестированная программа на показательных испытаниях не работает;
•	функциональность, о которой долго просил заказчик, и которая была, наконец, добавлена в продукт, и новая версия торжественно отослана заказчику, таинственным образом исчезла из продукта;
•	на компьютере разработчика программа работает, а у заказчика - нет.
В перечисленных выше примерах проблема в версиях файлов. Там, где все работает корректно, присутствуют файлы одной версии, а там, где все плохо - другой. Но беда в том, что «версия всего продукта» -это абстрактное понятие. На деле есть версии отдельных файлов. Поэтому необходимо управлять версиями файлов, чтобы избежать вышеперечисленных проблем.
Эти проблемы серьезно тормозят внутреннюю работу: то разработчики и тестеры работают с разными версиями системы, то итоговая сборка системы требует специальных усилий всего коллектива. Более того, возможны неприятности на уровне управления. Различные курьезные ситуации, когда заявленная функциональность отсутствует или не работает, могут сильно портить отношения с заказчиком. Недовольный заказчик может потребовать даже денежной компенсации за то, что возникающие ошибки слишком долго исправляются.
Итак, становится понятно, что в программных проектах необходима специальная деятельность по поддержанию файловых активов проекта в порядке. Она и называется конфигурационным управлением (configuration management CM).
Выделим две основные задачи в конфигурационном управлении:
•	управление версиями;
•	управление сборками.
Первое отвечает за управление версиями файлов и выполняется в проекте на основе специальных программных пакетов - средств версионного контроля. Существует большое количество таких средств - Microsoft Visual SourceSafe, IBM ClearCase, cvn, subversion и др. Управление сборками - это автоматизированный процесс трансформации исходных текстов ПО в пакет исполняемых модулей, учитывающий многочисленные настройки проекта, настройки компиляции, и
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
197
интегрируемый с процессом автоматического тестирования. Эта процедура является мощным средством интеграции проекта, основой итеративной разработки.
Цели конфигурационного управления:
1.	Контроль: SCM позволяет отслеживать изменения в контролируемых объектах, обеспечивает соблюдение процесса разработки;
2.	Управление: SCM диктует процесс автоматической идентификации в ходе всего жизненного цикла ПО, обеспечивает простоту модификации и сопровождения ПО;
3.	Экономия средств: снизижается риск потерь от ротации кадров в организации, предоставить возможность сменить организацию-разработчика без перепроектирования;
4.	Качество.
Задачи конфигурационного управления:
•	идентификация конфигурации;
•	контроль конфигурации: контроль над изменениями материалов;
•	учет текущего состояния: состояние документов, состояние кода, состояние отдельных задач и всего проекта в целом;
•	управление процессом разработки;
•	управление сборкой;
•	управление окружением;
•	отслеживание задач и проблем (в частности, отслеживание ошибок).
2.11.1, Единицы конфигурационного управления
Управление осуществляется только измененными файлами. Например, файлы с используемым в проекте купленным ПО должны находиться на CD-дисках или в локальной сети. Книги, документы с внешними стандартами, используемыми в проекте и пр. также должны просто храниться там, где каждый желающий их может взять. Как правило, такой информации в проекте немного, но, разумеется, она должна быть в порядке. Однако ради этого специальный вид деятельности в проекте не нужен.
Итак, конфигурационное управление имеет дело с меняющимися в процессе продуктами, состоящими из наборов файлов. Такие продукты принято называть единицами конфигурационного управления (configuration management items). К ним относятся, например:
198
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
•	пользовательская документация;
•	проектная документация;
•	исходные тексты ПО;
•	пакеты тестов;
•	инсталляционные пакеты ПО;
•	тестовые отчеты.
У каждой единицы конфигурационного управления должно быть следующее.
Структура - набор файлов. Например, пользовательская документация в html должна включать индекс-файл и набор ht ml-фай лов, а также набор вынесенных изображений (gif или jpeg-файлы). Эта структура должна быть хорошо определена и отслеживаться при конфигурационном управлении: все файлы не должны быть потеряны и обязаны присутствовать, иметь одинаковую версию, корректные ссылки друг на друга и т.д.
Указать ответственное лицо и, возможно, группу разработчиков, а также более широкую и менее ответственную группу тех, кто пользуется этой информацией. Например, определенной программной компонентой могут в проекте пользоваться многие сотрудники, но отвечать за ее разработку, исправление ошибок и пр. должен кто-то один.
Практика конфигурационного управления определяет, кто и в каком режиме, а также в какое место выкладывает новую версию элемента конфигурационного управления в средство управления версиями. Здесь же определяются правила именования и комментирования элемента в этой версии, дальнейшие манипуляции с ним там и пр. Сюда относятся и более высокоуровневые правила, связанные, например, с правилами изменения тестов и тестовых пакетов при изменении кода. Однако здесь находится т.н. «водораздел» между конфигурационным управлением и иными видами деятельности в проекте.
Автоматическая процедура контроля целостности элемента - например, сборка для исходных текстов программ, есть не у всех элементов, например, может не быть у документации, тестовых пакетов.
Элементы конфигурационного управления могут образовывать иерархию, например, как показано на рис.2.2.
Первоначально управление конфигурацией включало в себя и управление требованиями, и управление изменениями, и контроль версий. Это зафиксировано во всех основных стандартах, касающихся
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
199
Рис. 2.2. Пример иерархии элементов конфигурационного управления
УК. С точки зрения стандартов программной инженерии этот подход действует и сейчас.
С теоретической точки зрения вполне разумно оставить все три взаимосвязанных процесса - управление требованиями, управление изменениями и версионный контроль - в рамках единого процесса управления конфигурацией [14]. Но на практике дело в настоящий момент обстоит иначе.
Трудно сказать, что было первопричиной - реальные потребности пользователей или маркетинговые стратегии фирм-производителей инструментальных средств, но в настоящий момент управление требованиями в подавляющем большинстве проектов рассматривается как отдельный процесс, а управление изменениями в качестве отдельного процесса рассматривается только в половине проектов. В другой половине оно предстает как часть процесса управления конфигурацией. И только версионный контроль всегда рассматривается как часть управления конфигурацией.
2.11.2.	Управление версиями
1.	Управление версиями файлов. Поскольку программисты имеют дело с огромным количеством файлов, многие файлы в один момент могут быть необходимы нескольким людям и важно, чтобы все они постоянно составляли единую, как минимум, компилирующуюся
200
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
версию продукта, необходимо, чтобы была налажена работа с файлами с исходным кодом. Также может быть налажена работа и с другими типами файлов. В этой ситуации файлы оказываются самыми младшими (по иерархии включения) элементами конфигурационного управления.
2.	Управление версиями составных конфигурационных объектов. Одновременно может существовать несколько версий системы - и в смысле для разных заказчиков и в смысле одного проекта, одного заказчика, но как разный набор исходных текстов. И в том и в другом случае в средстве управления версиями образуются разные ветки. Остановимся подробнее на втором случае.
Каждая ветка содержит полный образ исходного кода и других артефактов, находящихся в системе контроля версий. Каждая ветвь может развиваться независимо, а может в определенных точках интегрироваться с другими ветвями. В процессе интеграции изменения, произведенные в одной из ветвей, полуавтоматически переносятся в другую. В качестве примера можно рассмотреть следующую структуру разделения проекта на ветки (рис.2.3).
Рис. 2.3. Один из вариантов разделения проекта на версионные ветки
VI.0 - ветвь, соответствующая выпущенному релизу. Внесение изменений в такие ветви запрещены и они хранят образ кода системы па момент выпуска релиза.
Fix VI.0.1 - ветвь, соответствующая выпущенному пакету исправлений к определенной версии. Подобные ветви ответвляются от ис
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
201
ходной версии, а не от основной ветви и замораживаются сразу после выхода пакета исправлений.
Upcoming (VI. 1) - ветвь, соответствующая релизу, готовящемуся к выпуску и находящемуся в стадии стабилизации. Для таких ветвей, как правило, действуют более строгие правила и работа в них ведется более формально.
Mainline - ветвь, соответствующая основному направлению развития проекта. По мере созревания именно от этой ветви отходят ветви готовящихся релизов.
WCF Experiment - ветвь, созданная для проверки некоторого технического решения, перехода на новую технологию, или внесения большого пакета изменений, потенциально нарушающих работоспособность кода на длительное время. Такие ветви, как правило, делаются доступными только для определенного круга разработчиков и уничтожаются по завершению работ после интеграции с основной веткой.
2.11,3.	Управление сборками
Итак, почему процедура компиляции и создания исполняемых файлов по исходным текстам проекта настолько важна? Дело в том, что она многократно выполняется каждым разработчиком на его собственном компьютере. И каждый разработчик использует собственную версию проекта. При этом различается;
•	набор подпроектов, собираемых разработчиком; он может собирать не весь проект, а только какую-то его часть; другая часть либо им не используется вовсе, либо не пересобирается очень давно, а по факту она давно изменилась;
•	отличаются параметры компиляции.
При этом если не собирать регулярно итоговую версию проекта, то общая интеграция может выявить много разных проблем:
•	несоответствие друг другу различных частей проекта;
•	наличие специфических ошибок, возникших из-за того, что отдельные проекты разрабатывались без учета параметров компиляции (в частности, переход в Visual Studio с debug на release версию часто сопро1/^ждаетсм появлением многочисленных проблем).
202
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
В связи с этим процедуру сборки проекта часто автоматизируют, то есть выполняют не из среды разработки, с помощью специального build-скрипта. Этот скрипт используется тогда, когда разработчику требуется полная сборка всего проекта. А также он применяется в процедуре непрерывной интеграции (continues integration), то есть регулярной сборке всего проекта. Как правило, процедура непрерывной интеграции включает в себя и регрессионное тестирование, и создание инсталляционных пакетов. Общая схема автоматизированной сборки представлена на рис.2.4. Тестировщики должны тестировать
Рис. 2.4. Общая схема автоматизированной сборки
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
203
по возможности итоговую и целостную версию продукта, так что результаты регулярной сборки оказываются очень востребованы. Кроме того, наличие базовой, актуальной, целостной версии продукта позволяет организовать разработку в итеративно-инкрементальном стиле, то есть на основе внесения изменений. Такой стиль разработки называется baseline-метод.
2.11.4.	Понятие baseline
Baseline - это базовая, последняя целостная версия некоторого продукта разработки, например, документации, программного кода и т.д. Подразумевается, что разработка идет не сплошным потоком, а с фиксацией промежуточных результатов в виде текущей официальной версии разрабатываемого актива. Принятие такой версии сопровождается дополнительными действиями по оформлению, сглаживанию, тестированию, включению только законченных фрагментов и т.д. Этот результат можно посмотреть, отдать тестеровщикам, передать заказчику и т.д. Baseline служит хорошим средством синхронизации групповой работы.
Baseline может быть совсем простой - веткой в средстве управления версиями, где разработчики хранят текущую версию своих исходных кодов. Единственным требованием в этом случае может быть лишь общая компилируемость проекта. Но поддержка baseline может быть сложной формальной процедурой, как показано на рис.2.5. Baseline может также поддерживаться непрерывной интеграцией.
Важно, что Baseline (особенно в случае с программными активами) не должна устанавливаться слишком рано. Сначала нужно написать какое-то количество кода, чтобы было что интегрировать. Кроме того, вначале много внимания уделяется разработке основных архитектурных решений, и целостная версия оказывается не востребованной. Но начиная с некоторого момента она просто необходима. Какой этот момент - решать членам команды. Наконец, существуют проекты, где автоматическая сборка не нужна вовсе - это простые проекты, разрабатываемые небольшим количеством участников, где нет большого количество исходных текстов программ, проектов, сложных параметров компиляции.
204
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Рис. 2.5. Схема процедуры Baseline
2.11.5.	Стандартизация процесса управления конфигурацией
Для определения основных положений процесса управления конфигурацией представляется разумным воспользоваться существующими стандартами, описывающими процесс УК [14]. При этом следует определить тот стандарт, который будет в наибольшей степени соответствовать потребностям конкретного предприятия.
Все стандарты можно условно разделить на виды, в зависимости от широты их области действия [14].
•	Международные стандарты, действующие без ограничений во всех странах.
•	Государственные или отраслевые стандарты, действующие для группы предприятий или организаций, объединяемых некоторыми общими признаками.
•	Внутренние стандарты предприятия, действующие для конкретного предприятия и учитывающие специфику этого предприятия.
Некоторые часто используемые международные стандарты приведены ниже (см. таблицу 2.3).
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
205
Таблица 2.3. Международные стандарты, описывающие процесс УК
Стандарты и руководства	Описание
IEEE/EIA 12207.0-1996, Industry Implementation of International Standard ISO/IEC 12207:1995 (ISO/IEC12207) Standard for Information Technology -Software Lifecycle Processes	Устанавливает общую структуру процессов жизненного цикла (ЖЦ) программных средств.
IEEE/EIA 12207.1-1996, Lifecycle data.	Представляет рекомендации о характере данных, которые должны сохраняться при выполнении задач и работ, приведенных в IEEE/EIA 12207.0
IEEE/EIA 12207.2-1996, Implementation Considerations	Представляет рекомендации по реализации требований стандарта IEEE/EIA 12207.0.
ISO 9000-3: Quality Mgmt & Quality Assurance Stds-Part 3: Guidelines for the application of ISO 9001 to the development, supply and maintenance of software	Излагает рекомендации по применению ISO 9001 в организациях, разрабатывающих, поставляющих и сопровождающих ПО.
206
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
В качестве примера отраслевого стандарта можно привести MIL-STD-2549 «Configuration Management Data Interface», который детализирует требования для обмена данными между правительственными системами конфигурационного управления.
Международные и отраслевые стандарты не дают возможности напрямую применять описываемый в них процесс на уровне предприятия, так как само описание процесса УК в них приведено недостаточно подробно для прямого использования.
Обычная практика использования таких стандартов состоит в их адаптации для нужд конкретного предприятия. При адаптации стандарта определяется, в какой степени он будет использоваться на предприятии:
•	полностью;
•	за исключением определенных ситуаций;
•	отдельные положения стандарта.
Далее положения стандарта детализируются и дополняются с учетом специфики конкретного предприятия.
Для детализации процесса УК при его адаптации можно использовать методологии, разработанные различными международными организациями и фирмами (например, Rational) [14]. Такие методологии обычно содержат более детальное описание процесса и часто имеют руководства по применению инструментальных средств автоматизации, что существенно упрощает адаптацию методологии. Впрочем, бывают ситуации, когда специфика предприятия настолько отличается от общих правил, предлагаемых методологией, что проще детализировать процесс УК самостоятельно, без привязки к какой-либо методологии.
Итогом такой адаптации обычно является внутренний стандарт предприятия на процесс управления конфигурацией. Таким образом, прослеживается следующая цепочка [14]:
•	международный стандарт - определение общих положений процесса УК;
•	методология, соответствующая выбранным общим положениям - детализация процесса УК на основе проверенных на опыте многих компаний принципов и правил;
•	стандарт предприятия - уточнение процесса и его адаптации к нуждам конкретного предприятия.
Стандарт предприятия требует серьезной проработки своих положений, и работа по вводу его в действие обычно занимает несколь
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
207
ко лет. До момента ввода в действие стандарта предприятия в проектах могут действовать отдельные нормативные и организационнораспорядительные документы.
Далее будем рассматривать управление требованиями как отдельный процесс, не являющийся частью процесса управления конфигурацией, хотя и тесно с ним связанный (хотя это и противоречит ряду стандартов, не выделяющих управление требованиями в отдельный процесс).
Разделение управления конфигурацией и управления изменениями на отдельные процессы или рассмотрение единого процесса управления конфигурацией с технологической точки зрения имеет мало отличий. Вопрос о разделении рассматривается главным образом с точки зрения организационной структуры, обеспечивающей выполнение единого процесса или двух взаимосвязанных процессов, и с точки зрения использования инструментальных средств автоматизации процесса управления конфигурацией и управления изменениями. Авторам удавалось одинаково успешно реализовывать проекты и в том, и в другом случае.
Далее, если явно не оговорено противное, управление изменениями всегда будет рассматриваться как часть процесса управления конфигурацией, что соответствует стандартам, используемым при определении процесса УК.
ПОдробно рассмотрим один из таких стандартов - ГОСТ Р ИСО/МЭК 12207 «Информационные технологии. Процессы жизненного цикла программных средств».
Для рассмотрения этого стандарта есть несколько важных причин 114].
1.	Стандарт ГОСТ Р ИСО/МЭК 12207 является российским стандартом, официально введенным в действие на территории Российской Федерации.
2.	Рассматриваемый стандарт создан на основе одного из наиболее популярных международных стандартов в сфере информационных технологий - ISO/IEC 12207:1995 (ISO/IEC12207) Standard for Information Technology - Software Lifecycle Processes.
3.	Популярные методологии разработки ПС (такие как Rational) основываются на ISO/IEC 12207:1995 (ISO/IEC12207) Standard for Information Technology - Software Lifecycle Processes.
208
2. ЦЕЛИ И ПРИНЦИПЫ ДОКУМЕНТИРОВАНИЯ ПС
Российский стандарт ГОСТ Р ИСО/МЭК 12207 рассматривает процессы жизненного цикла (ЖЦ) программных средств (ПС) и подразделяет их на три группы:
•	основные;
•	вспомогательные;
•	организационные.
Стандарт ГОСТ Р ИСО/МЭК 12207 устанавливает общую структуру процессов жизненного цикла (ЖЦ) программных средств (ПС), определяет процессы, работы и задачи, выполняемые в ходе ЖЦ ПС.
Процесс конфигурационного управления определяется как вспомогательный процесс (рис.2.6). В соответствии с рассматриваемым стан-
- ЗАКАЗ
- ПОСТАВКА
-РАЗРАБОТКА
-ЭКСПЛУАТАЦИЯ
- сопровождение
- АОКУМСНТИРОВАНИС - УПРАВЛЕНИЕ КОНФИГУРАЦИЕЙ - 0БЕСП6ЧБЫИЕ КАЧЕСТВА
- УПРАВЛЕНИЕ
- СОЗДАНИЕ
ИНФРАСТРУКТУРЫ
- УСОВЕРШЕНСТВОВАНИЕ
- ОБУЧЕНИЕ
- ВЕРИФИКАЦИЯ
- АТТЕСТАЦИЯ
- СОВМЕСТНЫЙ АНАЛИЗ
- АУДИТ
- ранение проблем
Рис. 2.6. Процессы жизненного цикла ПС по ГОСТ Р ИСО/МЭК 12207
дартом, данный процесс состоит из следующих работ.
1.	Подготовка процесса. Должен быть разработан план управления конфигурацией. План должен определять: работы по управлению конфигурацией; процедуры и график выполнения данных работ; ор-ганизацию(и), ответственную(ые) за выполнение данных работ; связь данной организации(й) с другими организациями, например, по разработке и сопровождению программных средств. План должен быть
2.11. ДОКУМЕНТАЦИЯ СОПРОВОЖДЕНИЯ
209
документально оформлен и выполнен (план может быть частью плана управления конфигурацией системы).
2.	Определение конфигурации. Должна быть определена схема обозначения программных объектов и их версий (объектов программной конфигурации), которые контролируются при реализации проекта. Для каждого программного объекта и его версий должны быть определены: документация, в которой фиксируется состояние его конфигурации; эталонные версии и другие элементы обозначения.
3.	Контроль конфигурации. Анализ и оценка изменений; принятие или непринятие заявки; реализация, верификация и выпуск измененного программного объекта. Для каждого изменения должны отслеживаться проводимые аудиторские проверки, посредством которых анализируется каждое изменение, его причина и разрешение на его внесение. Должны быть выполнены контроль и аудиторская проверка всех доступных контролю программных объектов, которые связаны с критическими функциями безопасности или защиты.
4.	Учет состояний конфигурации. Должны быть подготовлены протоколы управления и отчеты о состоянии, которые отражают состояние и хронологию изменения контролируемых программных объектов, включая состояние их конфигурации. Отчеты о состоянии должны включать количество изменений в данном проекте, последние версии программных объектов, обозначения выпущенных версий, количество выпусков и сравнения программных объектов различных выпусков.
5.	Оценка конфигурации. Должны быть определены и обеспечены: функциональная законченность программных объектов с точки зрения реализации установленных к ним требований; физическая завершенность программных объектов с точки зрения реализации в проекте и программах всех внесенных изменений.
6.	Управление выпуском и поставка. Должны официально контролироваться выпуск и поставка программных продуктов вместе с соответствующей документацией. Оригиналы программ и документации должны сопровождаться в жизненном цикле. Программы и документация, связанные с обеспечением критических функций безопасности или защиты, должны обрабатываться, храниться, упаковываться и поставляться в соответствии с установленными правилами.
3. Пакеты программ для формирования отчетов
Очевидно, что у любого сотрудника компании большая часть времени уходит не на разработку программного обеспечения, а на написание отчетов и документации. Как показывает статистика [5], из восьми часов рабочего дня на документирование тратится один час. С точки зрения руководителей и заказчиков проекта это время является потерянным. Что же касается разработчиков, то и они не в восторге от такой рутины - им неинтересно составлять отчеты, тем более отчеты читабельные, то есть понятные не только их авторам.
Приведение в порядок только одного звена - документирования -ведет к повышению внутренней культуры предприятия, положительно сказываясь при этом на притоках внешних инвестиций, выражающихся в получении новых заказов на разработку.
За последние десятилетия сформировалось новое направление в программотехнике - CASE (Computer-Aided Software/System Engineering) - в дословном переводе - разработка программного обеспечения информационных систем при поддержке (с помощью) компьютера. В настоящее время не существует общепринятого определения CASE, термин CASE используется в весьма широком смысле. Первоначальное значение термина CASE, ограниченное вопросами автоматизации разработки только лишь программного обеспечения (ПО), в настоящее время приобрело новый смысл, охватывающий процесс разработки сложных автоматизированных информационных систем (АИС) в целом. Теперь под термином CASE-средства понимаются программные средства, поддерживающие процессы создания и сопровождения ИС, включая анализ и формулировку требований, проектирование прикладного ПО (приложений) и баз данных, генерацию кода, тестирование, документирование, обеспечение качества, конфигурационное управление и управление проектом, а также другие процессы.
210
3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ 211
CASE-средства вместе с системным ПО и техническими средствами образуют полную среду разработки АИС [15].
В разряд CASE-средств попадают как относительно дешевые системы для персональных компьютеров с весьма ограниченными возможностями, так и дорогостоящие системы для неоднородных вычислительных платформ и операционных сред. Так, современный рынок программных средств насчитывает около 300 различных CASE-средств, наиболее мощные из которых так или иначе используются практически всеми ведущими западными фирмами.
Обычно к CASE-средствам относят любое программное средство, автоматизирующее ту или иную совокупность процессов жизненного цикла ПО и обладающее следующими основными характерными особенностями:
•	мощные графические средства для описания и документирования ИС, обеспечивающие удобный интерфейс с разработчиком и развивающие его творческие возможности;
•	интеграция отдельных компонент CASE-средств, обеспечивающая управляемость процессом разработки ИС;
•	использование специальным образом организованного хранилища проектных метаданных (репозитория).
Интегрированное CASE-средство (или комплекс средств, поддерживающих полный ЖЦ ПО) содержит следующие компоненты:
•	репозиторий, являющийся основой CASE-средства, который должен обеспечивать хранение версий проекта и его отдельных компонентов, синхронизацию поступления информации от различных разработчиков при групповой разработке, контроль метаданных на полноту и непротиворечивость;
•	графические средства анализа и проектирования, обеспечивающие создание и редактирование иерархически связанных диаграмм (DFD, ERD и др.), образующих модели ИС;
•	средства разработки приложений, включая языки 4GL и генераторы кодов;
•	средства конфигурационного управления;
•	средства документирования;
•	средства тестирования;
•	средства управления проектом;
•	средства реинжиниринга.
212 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
Все современные CASE-средства могут быть классифицированы в основном по типам и категориям. Классификация по типам отражает функциональную ориентацию CASE-средств на те или иные процессы ЖЦ. Классификация по категориям определяет степень интегрированности по выполняемым функциям и включает отдельные локальные средства, решающие небольшие автономные задачи (tools), набор частично интегрированных средств, охватывающих большинство этапов жизненного цикла ИС (toolkit) и полностью интегрированные средства, поддерживающие весь ЖЦ ИС и связанные общим репозиторием. Помимо этого, CASE-средства можно классифицировать по следующим признакам [15]:
•	применяемым методологиям и моделям систем и БД;
•	степени интегрированности с СУБД;
•	доступным платформам.
Классификация по типам в основном совпадает с компонентным составом CASE-средств и включает следующие основные типы:
•	средства анализа (Upper CASE), предназначенные для построения и анализа моделей предметной области (Design/IDEF (Meta Software), BPwin (Logic Works));
•	средства анализа и проектирования (Middle CASE), поддерживающие наиболее распространенные методологии проектирования и использующиеся для создания проектных спецификаций (Vantage Team Builder (Cayenne), Designer/2000 (ORACLE), Silverrun (CSA), PRO-IV (McDonnell Douglas), CASE.Аналитик (МакроПроджект)). Выходом таких средств являются спецификации компонентов и интерфейсов системы, архитектуры системы, алгоритмов и структур данных;
•	средства проектирования баз данных, обеспечивающие моделирование данных и генерацию схем баз данных (как правило, на языке SQL) для наиболее распространенных СУБД. К ним относятся ERwin (Logic Works), S-Designor (SDP) и DataBase Designer (ORACLE). Средства проектирования баз данных имеются также в составе CASE-средств Vantage Team Builder, Designer/2000, Silverrun и PRO-IV;
•	средства разработки приложений. К ним относятся средства 4GL (Uniface (Compuware), JAM (JYACC), PowerBuilder (Sybase), Developer/2000 (ORACLE), New Era (Informix), SQL Windows
3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ 213
(Gupta), Delphi (Borland) и др.) и генераторы кодов, входящие в состав Vantage Team Builder, PRO-IV и частично - в Silverrun;
•	средства реинжиниринга, обеспечивающие анализ программных кодов и схем баз данных и формирование на их основе различных моделей и проектных спецификаций. Средства анализа схем БД и формирования ERD входят в состав Vantage Team Builder, PRO-IV, Silverrun, Designer/2000, ERwin и S-Designor. В области анализа программных кодов наибольшее распространение получают объектно-ориентированные CASE-средства, обеспечивающие реинжиниринг программ на языке C++ (Rational Software, Object Team (Cayenne)).
Вспомогательные типы включают:
•	средства планирования и управления проектом;
•	средства конфигурационного управления;
•	средства тестирования;
•	средства документирования.
Многие современные программисты активно пользуются Javadoc, генератором технологической документации в формате HTML. Документация формируется из комментариев исходного кода на Java от Sun Microsystems. Javadoc является стандартом для документирования классов Java. Большинство сред разработки программного обеспечения автоматически генерируют HTML-документацию, используя Javadoc.
Комментарии документации применяют для:
•	документирования классов,
•	интерфейсов,
•	полей (переменных),
•	конструкторов,
•	методов, • пакетов.
В каждом случае комментарий должен находиться перед документируемым элементом. Однако это средство может применяться исключительно для создания отдельных частей руководства программиста и качество его работы во многом зависит от качества комментариев в исходном тексте программы.
Еще одним современным средством документирования исходных текстов программ является Doxigen (о его использовании упоминалось в разделе 2.2.). Это кроссплатформенная система документиро
214 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
вания исходных текстов, которая поддерживает такие языки как C++, Си, Objective-C, Python, Java, IDL, PHP, С, Фортран, VHDL и, частично, язык D. Doxygen генерирует документацию на основе набора исходных текстов и также может быть настроен для извлечения структуры программы из недокументированных исходных кодов. Возможно составление графов зависимостей программных объектов, диаграмм классов и исходных кодов с гиперссылками.
Что касается написания других типов документации, то здесь не получается ограничиться генераторами на основе программного кода. В течение многих лет создаются и совершенствуются программные системы, позволяющие создать полный набор программной документации на основе имеющихся стандартов.
Традиционные процессы авторской разработки и публикации длительны и неэффективны, что, в результате, значительно влияет на качество информационного материала, сопутствующего выпускаемой продукции. Обычно при создании документации используется содержимое из различных источников, которое просто перемещается путем «копирования и вставки» вместо того, чтобы использовать единый источник в различных представлениях. Обновление, требующее определения местонахождения и изменения фрагмента в различных материалах, перевод, повторное форматирование и публикация - длительный и неэффективный процесс. Это приводит к увеличению ошибок и неточностей в информационных материалах, и соответственно, к снижению качества публикаций. В разделах 3.3.5.-3.3.7. приводится краткое описание возможностей программного обеспечения, работающего по принципу единого источника.
3.1.	Особенности работы в Microsoft Word и Open Office для технического писателя
Текстовый процессор Microsoft Word, а также его свободно распространяемый аналог OpenOfice настолько часто используются для подготовки различного рода документов, что всякому пользователю известны основные принципы работы с этими программами. Однако работа с большими документами требует более глубоких знаний данных
3.1. ОСОБЕННОСТИ РАБОТЫ В MS WORD И OPEN OFFICE 215
программ. Можно без проблем сверстать небольшой документ (10-15 страниц), не пользуясь стилями, перекрестными ссылками и прочими инструментами текстового процессора, написать оглавление вручную и т.д. Однако при создании большого документа (более 100 страниц) такой «стиль» верстки приведет к росту времени работы с документом, росту числа ошибок оформления и ошибочных ссылок. В данном разделе рассмотрим приемы работы с текстовым процессором Microsoft Word, основанные на личном опыте автора пособия и статье [19]. Основная задача данного раздела состоит в том, чтобы предостеречь читателя от наиболее распространенных ошибок, совершаемых при оформлении документов. Кроме того, здесь показано, каким образом можно добиться соответствия документа, созданного в Microsoft Word, некоторым специфическим требованиям ГОСТ. Те же самые рекомендации подходят и для работы в свободно распространяемом Open Office Writer.
Будем полагать, что читатель хорошо знаком с основными механизмами работы Microsoft Word, в частности, умеет пользоваться стилями, автоматической нумерацией названий и перекрестными ссылками.
Перечисленные рекомендации в целом направлены на создание документов, обладающих следующими свойствами [19].
Устойчивость: длительное редактирование и многократные правки документа не приводят к неожиданным самопроизвольным изменениям форматирования или сбоям в работе Microsoft Word.
Переносимость: на разных компьютерах, разных версиях операционной системы и Microsoft Word документ выглядит и обрабатывается примерно одинаково.
Наследуемость: каждый следующий автор, принимая документ в обработку, может быстро разобраться в том, какими методами выполнялось его форматирование, в частности, понять состав и назначение используемых стилей.
Поддерживаемость: форматирование документа в целом, а также абзацев и строк, несущих схожую смысловую нагрузку (например, всего основного текста или всех врезок), при необходимости можно изменить, выполнив минимальный объем ручной работы.
3.1.1.	Рекомендации по использованию стилей
Именование стилей
Бессистемное присвоение имен создаваемым стилям может привести к тому, что через некоторое время в них будет трудно разобраться
216 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
даже самому автору. Поэтому при создании стилей следует придерживаться определенных правил именования. Эти правила, вообще говоря, могут быть разными.
Например, имена стилей должны быть лаконичными, но внятными. Лучше стремиться к тому, чтобы назначение стиля было в целом понятно по его имени без дополнительных пояснений.
Рекомендуется набирать имена стилей латинским шрифтом. Не стоит употреблять в именах стилей символы национальных алфавитов, даже если используемая версия Microsoft Word это допускает.
Имена стилей целесообразно образовывать от английских слов и аббревиатур. Например, стиль для врезок лучше назвать Inset, а не Vrezka.
Не рекомендуется использовать в именах стилей пробелы. Пробелы можно просто пропускать или набирать вместо них символы подчеркивания.
Лучше всего всегда использовать один и тот же принцип для образования имен стилей из нескольких слов. Обычно части имени пишут либо слитно с прописной буквы (Note Import ant), либо со строчной через символ подчеркивания (note.important).
Нужно стараться составлять имена так, чтобы при лексикографическом упорядочении близкие по функционалу стили оказывались рядом. Например, inset .note, inset _ warning, не note и warning.
Целесообразно именовать стили так, чтобы они отчетливо выделялись в списке стандартных стилей. Например, каждое имя может начинаться каким-нибудь префиксом, стандартным для проекта или для организации.
Перечисленные рекомендации связаны еще и с тем, что документы Microsoft Word могут обрабатываться всевозможными утилитами производства других фирм. Это могут быть, например, конверторы для преобразования документов в формат HTML или WinHelp. Такое программное обеспечение не всегда корректно обрабатывает пробелы, символы национальных алфавитов и другие детали в именах стилей.
Создавая стили, следует принимать во внимание, что, возможно, с ними придется работать нескольким пользователям. Стили должны быть такими, чтобы всем пользователям, работающим с файлом, для которого созданы стили, было легко в них разобраться.
3.1, ОСОБЕННОСТИ РАБОТЫ В MS WORD И OPEN OFFICE 217
Использование только чистых стилей
Текст необходимо оформлять только стилями, не используя в добавление к ним ручное форматирование. Если возникает потребность оформить абзац или строку нестандартным для документа способом, лучше потратить время на создание дополнительного специального стиля.
Форматирование вручную, например, может привести к следующим последствиям. Допустим, все абзацы основного текста начинаются с красной строки, но появилась необходимость, чтобы первые абзацы разделов красной строки не имели. Можно вручную в каждом таком абзаце сделать нулевой отступ. Но если потребуется вернуть первым абзацам разделов отступ, эту работу снова придется выполнить вручную. Кроме того, без проведения эксперимента сложно сказать, что произойдет с абзацными отступами исправленных абзацев, если абзацный отступ будет изменен на уровне стиля.
Общий базовый стиль для нескольких схожих стилей. Нередко для схожих по функции фрагментов текста приходится создавать схожие по оформлению стили, различающиеся несколькими свойствами. Например, для врезок типа «замечание» и «совет» могут быть созданы стили inset „note и inset _ tip имеющие одинаковые свойства абзаца и шрифта, но разные рамки.
В подобных случаях целесообразно создать дополнительный стиль, обладающий всеми дублирующимися свойствами, а от него образовать все родственные стили с характерными для них индивидуальными особенностями.
Использование базового стиля позволяет:
•	быстро создавать новые родственные стили; если вернуться к приведенному примеру, это могут быть стили для других врезок: предостережение, важной информации, примеров и т.п.;
•	быстро менять свойства однотипных стилей, например, задать шрифт сразу для всех типов врезок.
Базовый стиль может не применяться в документе непосредственно, а служить только для создания и автоматического обновления производных стилей.
Символьные стили для выделенного текста
Часто возникает необходимость так или иначе изменить начертание, размер или шрифт некоторых слов в тексте (например, выделить названия элементов интерфейса полужирным начертанием). Для это
218 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
го принято пользоваться соответствующими кнопками (например, Полужирный или Курсив) и комбинациями клавиш.
Однако подобная практика влечет за собой ряд неудобств. В частности, если после написания текста возникнет необходимость поменять начертание или размер шрифта сразу для многих однотипных элементов, то придется менять параметры каждого выделенного фрагмента вручную.
Поэтому удобнее создавать символьные стили для выделенных элементов текста. В таком случае при необходимости внести изменение в стиль можно менять его параметры только один раз. Отличительный признак символьных стилей: у них нет параметров, свойственных абзацу. Для каждого символьного стиля можно назначить комбинацию клавиш. Таким образом, упростится процесс применения символьных стилей.
Стиль для обычного текста
Стиль Обычный, которым большинство авторов имеет обыкновение набирать основной текст документа, является базовым для стилей заголовков, а также ряда служебных стилей: колонтитулов, номеров страниц и т.п. Вместе с тем время от времени может возникать необходимость изменить форматирование основного текста.
Поэтому, используя стиль Обычный, есть вероятность попасть в одну из следующих неприятных ситуаций.
Свойства стиля Обычный изменяются вручную. Соответствующим образом меняются свойства всех стилей, которые на нем основаны. В результате тратится время на исправление съехавших заголовков, колонтитулов и номеров страниц.
Все абзацы основного текста форматируются вручную. Если потребность в изменении форматирования основного текста возникает снова, приходится выполнять эту работу еще раз. Для основного текста рекомендуется сссдавать отдельный стиль, например, с названием my_normal.
Стиль для рисунков
Рисунок в документе принято снабжать подрисуночной подписью. Если рисунок оказывается внизу страницы, подрисуночная подпись может переместиться на следующую страницу, что некрасиво, а главное, практически лишает ее смысла.
Чтобы избежать отрыва подрисуночной подписи от рисунка, рекомендуется создавать для рисунков специальный стиль, обладающий
3.1. ОСОБЕННОСТИ РАБОТЫ В MS WORD И OPEN OFFICE 219
свойством Не отрывать от следующего. Этот стиль всегда назначается абзацу, в котором находится рисунок.
Стиль для заголовков таблиц
Аккуратный внешний вид таблицы в документе Microsoft Word помимо всего прочего определяется некоторыми особенностями поведения заголовков столбцов.
Для строки заголовков столбцов рекомендуется задать свойство Повторять как заголовок на каждой странице. Тогда при перетекании таблицы со страницы на страницу заголовки столбцов будут дублироваться в начале каждого продолжения таблицы.
Чтобы на той странице, с которой таблица начинается, никогда не оставалась только строка с заголовками столбцов, рекомендуется задать для последних свойство абзаца Не отрывать от следующего.
Стиль для заголовка содержания
Отсутствие отдельного стиля для заголовка содержания ведет к ряду весьма неприятных ошибок. Часто авторы оформляют заголовок содержания стилем заголовка первого уровня (Заголовок 1). В этом случае содержание документа является ссылкой на само себя.
В текстовом процессоре Microsoft Word имеется активная по умолчанию функция автоматического распознавания стилей. Поэтому, если вручную отформатировать заголовок содержания так, чтобы он выглядел как заголовок первого уровня, ему будет принудительно назначен стиль Заголовок 1. В результате ссылка на содержание снова окажется в содержании. Конечно, можно отключить эту функцию. В этом случае но при создании документов на другом компьютере, данная функция может оказаться включена.
Чтобы избежать подобной ошибки, рекомендуется создавать для заголовка содержания специальный стиль, основанный на стиле Обыч::ый.
3.1.2.	Особенности оформления рисунков
Вставленные рисунки
Как известно, в текстовом процессоре Microsoft Word предусмотрено три способа включения графического изображения в документ:
•	вставка в документ графического файла;
•	вставка в документ ссылки на графический файл;
220 3, ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
•	вставка в документ и самого графического файла, и ссылки на него.
Вставка в документ ссылок на графические файлы имеет следующие преимущества.
Большое количество вставленных рисунков часто приводит к тому, что Microsoft Word начинает работать нестабильно. Рисунки могут перестать отображаться, они будут потеряны и, возможно, их придется подготовить заново. Со связанными рисунками таких проблем практически не возникает.
Вставленный рисунок не всегда удается корректно извлечь с оригинальным разрешением. А это иногда требуется, например, чтобы поместить снимок экрана из документации в статью или рекламную листовку. Связанный рисунок всегда доступен в виде оригинального графического файла.
При редактировании можно переслать рисунки, в совокупности обычно имеющие ощутимый объем, однократно, а затем обмениваться только самим документом.
Сколько бы раз рисунок ни повторялся в документе, хранится одна его копия. Если такой рисунок изменяется, достаточно однократно заменить старый файл на новый. Это особенно актуально для значков, пиктограмм и графических кнопок.
В случае небольших изменений иногда бывает проще отредактировать снимок экрана в графическом редакторе, чем сделать его повторно. Связанный рисунок, в отличие от вставленного, всегда можно корректно отредактировать.
Единственное бесспорное преимущество вставленных рисунков состоит в том, что этот способ избавляет авторов от необходимости создавать и поддерживать каталог иллюстраций.
Перекрестная ссылка на рисунок согласно требованиям ГОСТ
Эта рекомендация в равной мере относится к рисункам и таблицам, но далее без ограничения общности будем рассматривать ссылки на рисунки.
Согласно требованиям ГОСТ 2.105 ссылка на рисунок оформляется следующим образом:
•	если ссылка предшествует рисунку: рис. 25;
•	если ссылка следует за рисунком: см. рис. 25.
3.1. ОСОБЕННОСТИ РАБОТЫ В MS WORD И OPEN OFFICE 221
Проблема заключается в том, что соответствующая функция Microsoft Word по умолчанию не поддерживает ни ссылок типа «Рис.», ни хотя бы ссылок только на номер (последнее присутствует в функ-ционале Open Office). В лучшем случае можно получить перекрестную ссылку вида Рисунок 25. Тем не менее, существует вполне корректный способ сделать ГОСТовскую перекрестную ссылку.
Прежде, чем создавать перекрестную ссылку, нужно вставить название рисунка. Это делается с помощью команды «Вставить название» на закладке «Ссылки» (MS Word 2007 и выше). По умолчанию подрисуночные подписи имеют формат «Рисунок», поэтому придется создать собственное название, которое будет записано как «Рис.» (рис.3.1). Для этого нужно нажать кнопку «Создать» и в открывшемся окне (на рис.3.1 оно находится слева) написать название неизменяемой части подписи - «Рис.».
Создать перекрестную ссылку (закладка «Вставка» команда «Перекрестная ссылка») (рис.3.2), указав, что вставляются только постоянная часть (текст «рис.») и номер рисунка.
3.1.3.	Прочие рекомендации
Заголовки списков
Часто возникает ситуация, когда заголовок маркированного или нумерованного списка остается на одной странице, а сам список переносится на следующую. Чтобы избежать этого следует назначать заголовку списка свойство абзаца Не отрывать от следующего. Тогда под заголовком читатель будет видеть хотя бы первый пункт списка. Желательно создавать для заголовков списков специальный стиль.
Если список состоит из 2-3 коротких пунктов, то целесообразно назначать свойство абзаца Не отрывать от следующего всем пунктам кроме последнего.
Желательно, чтобы строки таблиц не разрывались
Конечно, таблица таблице рознь, но обычно разрыв строки таблицы (т.е. перетекание строки таблицы со страницы на страницу) смотрится плохо. Поэтому рекомендуется в свойствах таблицы отменять установленное по умолчанию свойство Разрешить разрыв строки.
Рамки в соответствии с требованиями ЕСКД на каждой странице
222 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
Рис. 3.1. Вставка названия рисунка
Стандарты группы ЕСКД требуют, чтобы в документах определенных типов на каждой странице присутствовали рамки с атрибутивной информацией. Создание регулярных рамок вокруг текста является проблемой, так как очевидных штатных средств сделать это в Microsoft Word не предусмотрено.
Для реализации таких рамок применяется следующий прием. Рамка любой нужной конфигурации создается с помощью средств рисования и представляет собой плавающий рисунок. Чтобы рамка отображалась на каждой странице, этот рисунок связывают с абзацем в любом из колонтитулов.
Разрыв страницы
3.1, ОСОБЕННОСТИ РАБОТЫ В MS WORD И OPEN OFFICE 223
Рис. 3.2. Вставка названия рисунка
Одной из самых распространенных ошибок в больших документах является попытка добиться переноса каких-либо элементов текста на следующую страницу с помощью последовательности новых абзацев. Как только в такой документ вносятся какие-либо изменения, возникает необходимость сразу же исправлять такой перенос.
В таких случаях всегда необходимо использовать признак С новой страт ицм или символ разрыва страницы.
Неразрывные пробелы
Принято вставлять неразрывный пробел в следующих случаях:
•	между числом и обозначением единицы измерения;
•	перед длинным тире;
•	при оформлении перекрестных ссылок между элементами ссылки;
224 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
•	при указании на какой-либо фрагмент документации (глава, раздел и т.д.) между названием этого фрагмента и его номером, а также в ряде других случаев.
3.2.	Экскурс в историю: система документирования Rational SoDA
При попытке поиска современных средств документирования система Google первыми же ссылками выдает информацию и статьи о Rational SoDA. Эти статьи написаны настолько хорошо и находятся на таких посещаемых ресурсах, что сперва можно не заметить - датированы они в лучшем случае первыми годами 2000-х. И только при желании скачать чудодейственное средство от Rational оказывается, что программа давно уже снята с реализации, а фирма IBM, в состав которой сейчас входит Rational, только ведет поддержку уже приобретенных копий программы. Тем не менее, технологии Rational до сих пор позволяют составлять оптимальные решения для каждого этапа в разработке ПО.
Почему SoDA и некоторые другие средства Rational сняты с продажи? Дело в том, что компания разработала более современную платформу, объединившую в себе самое лучшее из предыдущих решений для разработки программного обеспечения, Rational Jazz. IBM Rational Jazz - масштабируемая платформа с открытым кодом от IBM Rational для разработки программного обеспечения (ПО), которая предоставляет группе разработчиков, распределенной географически и во временных зонах, удобные средства для организации эффективного процесса командной работы [32]. Платформа Jazz стала доступна пользователям с 2008 года. Идея названия происходит от аналогии с музыкальным коллективом - джаз-бандом - коллективом высокопрофессиональных музыкантов, которые одновременно взаимодействуют и как команда под управлением дирижера, так и как отдельные виртуозы, в том случае, если надо исполнить соло-партию.
Rational Jazz - это одновременно и технология, и платформа для разработки ПО, которая делает процесс более открытым и прозрачным. С концептуальной точки зрения, IBM видит Jazz в трех аспектах - технология, взгляд IBM на то, как будет осуществляться разработка ПО в будущем и эволюция портфолио IBM Rational. Платформа
3.2. RATIONAL SODA
225
Jazz - это главное инвестирование IBM в создание масштабируемой, расширяемой системы по управлению жизненным циклом ПО, которая интегрирует современные технологии и инструменты командной работы с традиционными средствами разработки [32].
Данные, полученные в результате работы программ, могут относиться к коммерческой тайне и поэтому не подлежат разглашению. Даже заказчик системы не владеет всеми тонкостями разработки. Однако необходимо общаться с заказчиком (равно, как и с собственным руководством), и не на компьютерном сленге, а на языке, понятном всем окружающим, независимо от степени их владения информационными технологиями. Заказчику надо демонстрировать технические задания, планы работ, описания системы и т.д. Но это лишь малая толика проблем, связанных с отчетностью, которые позволяла решить SoDA (Software Documentation Automation) - оригинальная разработка компании Rational, значительно упрощающая процесс создания проектной документации и поддержания ее в течение всего цикла разработки ПО. Теперь эти проблемы можно решить и с помощью Rational Jazz.
Продукт SoDA был предназначен для автоматизации разработки проектной документации на всех фазах жизненного цикла программного обеспечения. Он позволял автоматически извлекать разнообразную информацию, получаемую на разных стадиях проектирования, и включать ее в выходные документы. При этом контролировалось соответствие документации проекту, проверялась взаимосвязь документов, обеспечивалось их своевременное обновление. Результирующая документация автоматически формировалась из множества источников, число которых не было ограничено. Тогда SoDA являлась уникальным продуктом и не подменяла ни одно из разработанных ранее средств отчетности. Она позволяла работать с единым источником и осуществлять контроль версий.
SoDA позволяла не зависеть от применяемых инструментальных средств. Связь с приложениями осуществлялась через стандартный программный интерфейс API. Переход на новые инструментальные средства не мог повлечь за собой дополнительных затрат по документированию проекта.
SoDA имела набор шаблонов документов, определяемых международным стандартом на программное обеспечение DOD 2167А. На основе этих шаблонов можно было без специального программирования создавать новые формы документов, определяемые пользователями.
226 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
Кроме того, данный инструмент позволял осуществлять отчетность по всем вышеприведенным стандартам - от ISO, заложенного в саму систему, до любых других, вплоть до придуманных в самой компании.
Пакет включал в себя графический редактор для подготовки шаблонов документов. Он позволял задавать необходимый стиль, фон, шрифт, определять расположение заголовков, резервировать места, где будет размещаться извлекаемая из разнообразных источников информация. Изменения автоматически вносились только в те части документации, на которые они повлияли в программе. Это позволяло сократить время подготовки документации за счет отказа от переге-нерации всей документации.
Система SoDA была реализована на базе издательской системы FrameBuilder и предоставляла полный набор средств по редактированию и верстке выпускаемой документации. В системе создавались таблицы требований к проекту, по которым можно проследить, как реализуются эти требования. Разные виды документации, сопровождающие различные этапы ЖЦ, связаны между собой, и можно было проследить состояние проекта от первоначальных требований до анализа, проектирования, кодирования и тестирования программного продукта.
Итоговым результатом работы системы SoDA являлся готовый документ (или книга). Документ мог храниться в файле формата SoDA (Frame Builder), который получался в результате генерации документа либо в формате MS Word, т.к. самые последние версии SoDA допускали интеграцию с MS Office. SoDA, по существу, представляла собой макрос, написанный для MS Word и особенно полезный при реализации крупных информационных проектов, в которых на составление документации и ее постоянную переработку обычно тратится очень много времени и сил разработчиков [5]. Также отчет можно было представить в формате HTML.
IBMrRational позволяла получить отчет или документ установленного образца с минимальными ручными правками, поскольку в ходе жизненного цикла процесса разработки программных систем создается большое количество комментирующих записей и сопроводительной информации в базах данных средств IBM Rational, которые и извлекались посредством IBM Rational SoDA в виде отчетного документа.
По задаваемым пользователем шаблонам SoDA компилировала документацию, собирая в один документ текстовые и графические дан
3.2. RATIONAL SODA
227
ные из различных источников, например из моделей, созданных в Rational Rose. Далее пользователь мог отредактировать полученный документ с помощью Microsoft Word или в издательских систем фирмы Adobe. Как и любая система отчетности, SoDA базировалась на тех данных сторонних программ. IBMrRational SoDA содержала более 70 шаблонов отчетов. Базируясь на них, IBM Rational SoDA поддерживала возможность стандартизации типов документов в рамках проек-тат'или стандартов компании. IBM Rational SoDA могла обеспечить соответствие проектной документации таким международным стандартам, как ISO, SEI СММ, IEEE, ат'также отечественным серии ГОСТ 19 и 34.
Шаблоны IBM Rational SoDA содержали информацию о формате документа, о его стиле и структуре, определяли расположение источника иГэлементов информации, которые следовало извлечь из хранилищ других инструментов IBM Rational.
IBM Rational SoDA могла автоматически генерировать документы и отчеты в формате HTML, что позволяло создать информационный портал для участников проекта, где можно было видеть текущее состояние проекта по его документам и отчетам. Подобный подход особенно полезен для объединения географически распределенных групп или групп, работающих на различных платформах.
Остановимся на первом режиме, когда за основу берется стандартный шаблон [5]. Известно, что компания Rational не только полностью описала процесс выпуска программного обеспечения, но и создала программные средства для каждого этапа этого процесса. Следовательно, каждый продукт сохранял данные, a SoDA по ним строила (компилировала) отчет.
С точки зрения Rational, получалась следующая последовательность этапов разработки приложений [5]:
•	бизнес-моделирование;
•	определение требований;
•	анализ и проектирование;
•	тестирование;
•	реализация;
•	внедрение.
Естественно, все этапы описаны детально, и на каждом из них предполагалось получение документа строго определенного образца (согласно RUP), после того как соответствующие данные были обра
228 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
ботаны той или иной программой из набора средств Rational. Так, на первом этапе при помощи SoDA можно было получить такие документы, например, как:
•	оценка организации заказчика,
•	словарь терминов предметной области,
•	коммерческое предложение,
•	бизнес-правила, и т.д.
На втором этапе можно было получить документы «Спецификация на программную систему», «Спецификация на функции системы».
В дальнейшем такой документ можно согласовать с заказчиком. Заметим, что первый этап называется «Бизнес-моделирование», это подразумевает использование на данном этапе средств визуального проектирования. Согласно технологии RUP, этим средством являлось Rational Rose. Оно позволяло на основе различных диаграмм получить полную бизнес-модель предприятия и модель проектируемой системы. Согласно технологии RUP, аналитик или проектировщик на этапе проектирования не только рисовали модель, создавая определенные связи между диаграммами, но и комментировали каждое свое действие на специальных полях либо подключали уже имеющиеся документы к модели. Разумеется, в результате получалась модель, полностью описывающая бизнес-процессы и программную систему. Однако она была понятной только узкому кругу лиц, представляющих себе полную картину проекта.
Перечислим, с какими программными продуктами работала SoDA и какие при этом отчеты могла создавать эта система [5]. Перечень программных продуктов и краткое описание созываемых ими отчетов приведено в таблице 3.1. В таблице 3.2 приведены расшифровка и описание типов диаграмм в Rose.
Представленного в таблице 3.1 списка хватает для правильной оценки возможностей продукта. К слову сказать, все вышеприведенные форматы отчетов могли бы помочь аналитикам и проектировщикам точно договориться с заказчиком о том, какую систему он хочет получить. Тестировщики могли бы генерировать отчеты по всем ошибкам (дефектам) и представлять их в удобной форме.
Для разработчиков был бы полезным отчет по классам, когда в наглядном виде можно было получить список классов с иерархией и описанием всех атрибутов и методов, не выходя из среды разработки [5]. С помощью только Rose и SoDA можно было сделать отчет по клас-
3.2. RATIONAL SODA
229
Таблица 3.1. Перечень отчетов, создаваемых SoDA
Продукт	Отчет комментарий	Характеристика/
ClearCase	Version	Отчет по версии одного элемента из репозитария ClearCase
	Vob	Отчет по состянию всех репозитариев в целом
	Element	Отчет по свойствам элементов
	Region	Отчет по всем используемым в проекте регионам
ClearQuest	All Defect in This State	Вывод всех дефектов, находящихся в указанном состоянии
RequisitePro	DocsReqts.doc	Отчет по требованиям и документам проекта
	Reqts.doc	Отчет по требованиям
	ReqtsAttrs.doc	Отчет по требованиям с выводом атрибутов требований
	ReqtsTraces.doc	Отчет по требованиям с использованием трассирования
TeamTest	BuildDetail.doc	Детальный отчет по тестированию с выводом ошибок, состояний и владельцев
	Build Summary.doc	Упрощенная версия вышеуказанного отчета
	ComputerDetail.doc	Отчет по характеристикам компьютеров, на которых проводилось тестирование, в том числе IP-адрес машины, на которой проигрывались тесты, наименование операционной системы
	ScriptDetail.doc	Отчет по скриптам тестирования, в том числе путь к файлу, имя его владельца
	TestDocDetail.doc	Отчет по тестовым документам
230 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
Окончание таблицы 3.1
Rose	498idd.doc	Отчет по списку документов, дизайну интерфейса, трассировке требований
г	498irs.doc	Список документов, требования к интерфейсу, квалификационный лист, трассировка требований
	498ocd.doc	Список документов, требования к продукту, квалификационный лист, трассировка требований
	498sdd.doc	CSCI-заключение, дизайн, трассировка требований
	Classes.doc	Отчет по всем классам в системе. Отчет следует иерархии и показывает связи
RUP	Actor Report.doc	Простой и быстрый отчет по характеристикам, отношениям и диаграммам состояний модели
Таблица 3.2. Расшифровка типов диаграмм в Rose
Аббревиатура IDD	Расшифровка Interface Design Description	Описание Описание интерфейса системы
IRS	Interface Requirements Specification	Спецификации на требования интерфейса
OCD	Operational Concept Description	Операционное ко нцептуальное описание
SDD	Software Design Description	Описание программного дизайна
SDP	Software Development Plan	План разработки
SRS	Software Requirements Specification	Спецификации на требования
SSS	System/Subsystem Specification	Спецификации на систему
3.2. RATIONAL SODA
231
сам той системы, которая уже написана и скомпилирована! Rose имела механизм так называемого обратного проектирования, когда исходный код превращался в модель Rose (преобразуясь в UML-нотацию). При обратном проектировании учитывались все составляющие классов, а также комментарии, которыми они снабжались, вследствие чего на выходе получалась полная модель всех классов (с иерархией). После этого достаточно было просто пропустить модель через систему генерации отчетов - и получался полноценный документ, описывающий систему классов программного продукта по всем мыслимым и немыслимым стандартам и правилам.
Понятно, что даже с помощью SoDA трудно было получить стопроцентно читабельный отчет для заказчика, но свои процентов восемьдесят такого отчета SoDA могла сгенерировать. Остальную правку можно возложить на плечи технического писателя, способного придать отчету (на этом этапе уже - документу) литературный вид.
Таким образом, SoDA представляла собой гибко настраиваемый продукт, имеющий собственный механизм составления отчетов по любым проектным данным. А это значит, что менеджер проекта мог всего один раз сформировать шаблоны отчетов, соответствующих внутренней политике компании, и впредь пользоваться только ими. Все лучшее, что было разработано в Rational SoDA теперь включено в IBM Rational Team Concert (RTC) - первый продукт на базе технологии Jazz, предоставляющий пользователям все преимущества технологий Jazz, а также интегрирующий клиента системы контроля версий, управление задачами, сборками, автоматически собирающий и консолидирующий информацию о проекте [32].
RTC является вариантом так называемого «толстого» клиента для платформы Jazz. Однако важно отметить, что RTC построен на базе Eclipse, что в свою очередь предоставляет широкие возможности для расширения функциональности самого продукта за счет плагинов для Eclipse.
Можно выделить следующие особенности RTC:
•	делает возможным общение в реальном времени для глобально распределенных команд, позволяя осуществлять разработку ПО автоматизировано, прозрачно и, как следствие, предсказуемо;
•	интегрирует систему контроль версий, задач, отчетность и сборку, которые работают в унисон;
232 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
•	обеспечивает диагностику проекта в реальном времени за счет автоматизированного сбора и консолидации информации;
•	предоставляет гибкое создание и внедрение процессов разработки ПО;
•	позволяет осуществить выбор для расширения функциональности за счет интеграции с другими продуктами IBM ClearQuest и ClearCase.
Что касается процесса документирования, то им занимается средство IBM Rational Rhapsody - среда разработки встраиваемых систем и приложений реального времени на основе визуального моделирования с использованием языка UML (Unified Modeling Language). Rhapsody пересматривает традиционный процесс разработки встраиваемых систем и приложений реального времени, устраняя традиционные барьеры между этапами процесса разработки основанного на документации [33].
Ключевые технологии Rhapsody, включают не только процесс документирования но и предшествующие ему стадии: визуальное моделирование, трассировку требований, исполнение, отладку и тестирование на уровне модели, генерацию кода, использование существующих наработок, динамическую синхронизацию модели и кода. Средство предусматривает организацию совместной работы в команде, улучшает взаимодействие в проекте и позволяют обнаруживать ошибки анализа и проектирования на ранних стадиях разработки. Таким образом, как и его предшественники Rational Rhapsody позволяет сократить ее время и стоимость за счет автоматизации процесса разработки.
Rhapsody предоставляет системным инженерам, разработчикам ПО и тестировщикам общую среду разработки на основе визуального моделирования, в которой можно проанализировать требования, спроектировать систему и программное обеспечение, сгенерировать и разработать приложение, а также быстро, эффективно и своевременно протестировать текущие результаты на любом этапе процесса разработки: от анализа требований до готовой встраиваемой системы. Rhapsody получила несколько престижных нагарад в области встраиваемых систем и считается лучшим решением для разработки на со-нове модели во многих отрасляхпромышленности: от автомобильной и авиакосмической до медицинской и транспортаной [33].
Разработчики встроенных программ могут использовать интегрированную среду разработки программного обеспечения для написания
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
233
кода на языках С, C++ или Java. Эта среда обеспечивает согласованность приложений благодаря использованию моделирования на основе языка UML и позволяет визуализировать и документировать проектирование встроенных приложений и приложений, р-^х «тающих в реальном масштабе времени. В частности, систем позволяет:
•	визуализировать архитектуру и проект с использованием отраслевого стандарта - языка UML;
•	генерировать блоки кода на языках С, C++ или Java;
•	осуществлять обратное проектирование кода С, C++ или Java для визуализации и документирования;
•	интегрироваться со средой разработки Eclipse для интегрированных операций программирования, моделирования и отладки;
•	автоматически обеспечивать согласованность архитектуры, проекта, кода и документации;
•	вести разработку приложений для автомобильной промышленности с использованием AUTOSAR;
•	использовать профиль MARTE для разработки архитектуры многоядерных приложений;
•	отслеживать требования в процессе проектирования, что обеспечивает выпуск на рынок качественного продукта;
•	обеспечить возможность совместной работы благодаря использованию функций выделения различий и объединения на основе моделей, включая интеграцию с решением IBM Rational Team Concert на базе Jazz.
В среде Rational Rhapsody Architect for Software предусмотрен новый, гибкий рабочий поток разработки кода, который синхронизирует разработку кода и моделей и помогает организации оперативнее реагировать на изменения.
Таким образом, в настоящее время Jazz - главное инвестирование IBM в создание масштабируемой, расширяемой системы по управлению жизненным циклом ПО, которая интегрирует современные технологии и инструменты командной работы с традиционными средствами разработки. Платформа представляет собою эволюцию портфолио IBM Rational, которое будет со временем все больше и больше внедрять Jazz. IBM Rational Team Concert- первый продукт на базе Jazz Platform, который получает положительные отзывы как ведущих аналитиков, так и клиентов и бизнес-партнеров компании IBM.
234 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
3.3. Технология единого источника
DocBook - приложение SGML или XML (проще говоря - популярный набор тегов), предназначенное для разметки документов, такое же, как HTML для разметки веб-документов. Официальный сайт программы H24J.
Преобразованием DocBook-документа в форматы, доступные для печатного или просто визуального представления (например, PDF, HTML, man-страницы) занимаются различные утилиты, обычно осуществляющие такое преобразование на основе настраиваемых шаблонов, или «таблиц стилей» (DSSSL или XSL), то есть происходит настоящая изоляция структуры документа от визуального представления.
В отличие от HTML-документа, DocBook-документ не рассматривается как конечный формат, поэтому, например, один документ в этом формате после преобразования может выглядеть и как один большой документ со сложной структурой, и как набор небольших простых документов-глав.
Несмотря на то, что DocBook разрабатывался для создания технической документации, он может использоваться и в других целях (для создания сайтов, с преобразованием в HTML; для создания презентаций).
DocBook является стандартом для документации на свободно распространяемое программное обеспечение. Его используют ведущие IT-компании и организации: IBM, Microsoft, Hewlett-Packard, Sun, Novell, WWW Consortium.
Применение DocBook наиболее эффективно в следующих ситуациях [28]:
•	когда объем документации велик;
•	когда в документацию постоянно приходится вносить изменения;
•	когда над документацией работает коллектив;
•	когда документация включает в себя четко структурированные составляющие;
•	когда необходимо строго выдерживать оформление множества документов;
•	когда документацию требуется выпускать в различных форматах;
•	когда требуется выпускать разные версии документации с отличающимся содержимым.
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
235
В то же время DocBook не является наглядным средством (хотя для него имеются графические редакторы) и требует усилий для освоения и для развертывания инструментария. Поэтому его не стоит использовать для текущей переписки или для небольших по объему документов.
По отношению к традиционным средствам подготовки документации - текстовым процессорам (например Microsoft Word), настольным издательским системам (например Adobe PageMaker) и языкам разметки (nroff, ТеХ, HTML) - DocBook обладает следующими преимуществами [28]:
•	возможность генерации документов в разном формате (онлайновых, печатных, help-файлов и т.д.) на основе единого источника;
•	авторам не приходится заботиться об оформлении - стиль верстки выходных документов задается программно;
•	поддержка коллективной работы над документацией, возможность повторного использования документов;
•	возможность создавать собственные расширения и разрабатывать на основе DocBook специализированные приложения.
Полная документация по данному средству на русском языке представлена на сайте [28].
Вкратце рассмотрим принцип единого источника применительно к задачам документирования и покажем, как именно этот принцип реализуется средствами технологической платформы DocBook/XML.
Для визуализации документов Docbook применяется, например, редактор Serna, который использует XSL стили для Docbook, созданные Норманом Уолшем для отображения документов Docbook со всеми изменениями на лету. Преимуществом применения XSL стилей является гибкий внешний вид документа с возможностью легко интернационализировать XML документы и добавлять автоматически создаваемый контент в помощь писателям.
3.3.1. Общие сведения о технологии единого источника
Технология единого источника нужна для того, чтобы выпускать качественную техническую документацию любого объема и уровня сложности. Теоретически любой комплект документов можно разрабатывать и сопровождать с помощью текстового процессора, т.е. по совре-
236 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
менным меркам вручную. Поручив это квалифицированным и добросовестным специалистам, можно избавиться от проблем с качеством, во всяком случае, до тех пор, пока у исполнителей будет хватать времени на самоконтроль: тщательную проверку всех результатов, правку и повторную проверку. На практике времени обычно не хватает. Дело не только в том, что конкуренция, бюджетные ограничения, давление со стороны заказчика и другие внешние обстоятельства вынуждают разработчиков выдерживать сжатые сроки, в конце концов, изыскивать ресурсы - задача управленца. Подготовка текста требует ресурсов, которые не сможет получить ни один менеджер. Ограничен ресурс человеческого внимания, поэтому с ростом объема документов и количества взаимосвязей между ними затраты на проверку нелинейно возрастают. Совместная работа нескольких авторов приводит к разнобою в документах. Вопреки стараниям разработчиков в техническую документацию закрадываются ошибки. Нарушаются правила оформления, одни и те же сведения в разных документах излагаются по-разному, документы обновляются несвоевременно, или обновленные части перемешиваются с устаревшими. Иными словами, теряется устойчивость качества: к нему можно стремиться, но за него невозможно ручаться. Особенно остро это проявляется при сопровождении больших комплектов технической документации.
Первая мера, на которую идут, чтобы удержать качество на должном уровне, - упрощение комплекта. Если не получается эффективно исправлять ошибки, то надо сузить для них «среду обитания». Запрещается и всякое дублирование информации. Количество перекрестных ссылок сводится к минимуму. Такой выход из положения не является оптимальным, потому что расплачивается за него пользователь. Он получает формально качественные документы, работать с которыми неудобно.
Теперь необходимо сделать две важные оговорки [18].
1. Большим объемом будем называть такой, при котором моральные и профессиональные достоинства разработчиков перестают гарантировать качество результатов их труда. Предположим, что с ростом объема текста и его структурной сложности (которая характеризуется количеством перекрестных ссылок, повторений, устойчивых формулировок, терминов, упоминаемых названий), любой проект рано или поздно перейдет эту грань.
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
237
2. Качество будем сводить к набору измеримых показателей, для каждого из которых можно установить минимальный порог, и, если он не достигнут, то документ (или комплект) считается неудовлетворительным.
Например,
•	все списки должны быть оформлены с определенным отступом от левого поля,
•	сведения только для службы технической поддержки никогда не должны включаться в документацию конечного пользователя, выводимые программой сообщения должны цитироваться в документации точно и т.д.
Измерить стилистику или логичность изложения невозможно, таким образом, на самом деле речь идет в важных, но не исчерпывающих характеристиках качества технической документации.
В противоположность упрощению комплекта подход единого источника предполагает автоматизацию труда разработчика, а не отказ от ручных операций заодно с их полезными результатами. Отлаженный автомат не совершает случайных ошибок, свойственных людям, поэтому проверять, править и перепроверять сгенерированные им документы не нужно вообще.
Правда, в некоторых видах работ современные автоматы не в состоянии превзойти даже человека средних способностей: даже посредственный верстальщик верстает лучше, чем самый совершенный автомат. Автомат соблюдает правила всегда, человек же нарушает их, заметив, что здесь и сейчас они действуют против тех целей, на достижение которых изначально направлены.
Первая цель — устойчивость качества, первый компромисс — согласие на известную формальность результата ради устранения формальных же ошибок.
Часто говорят, что единый источник ускоряет и удешевляет разработку технической документации. Это утверждение весьма спорно, поскольку за ускорение и удешевление одних операций мы расплачиваемся появлением дополнительных. В любом случае это не самостоятельные его преимущества, а другое выражение устойчивости качества. Неудовлетворительная документация никому не нужна даже мгновенно и бесплатно, а комфорт исполнителя сам по себе, как правило, не является целью проекта или организации. Ускорение и удешевление достигаются по сравнению с непредсказуемо долгим исправле
238 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
нием ошибок при ручной работе над большим комплектом. Очевидно, разработка обозримого (не «большого» в нашем смысле) комплекта традиционными средствами обходится дешевле, чем с использованием сложной технологии.
Второй компромисс — согласие на управляемый рост затрат в начале проекта ради предотвращения неуправляемого в конце.
Необходимость автоматизации разработки технической документации является следствием борьбы с проблемами, которые поражают любой крупный проект. Вместе с тем автоматизация открывает возможности, которые позволяют ставить новые цели, например:
•	повышение информативности технической документации;
•	сокращение сроков доставки актуальной технической документации пользователям;
•	предоставление пользователям инструмента для фиксации своего опыта или установившейся практики работы.
Технологии единого источника позволяют решать следующие задачи [18].
Автоматизация оформления документов по заданному макету или стандарту. Предполагается как публикация серии документов по одному отлаженному макету, так и публикация одного документа по нескольким макетам, например, руководство пользователя оформляется по ГОСТ 2.105-95 для поставки государственному заказчику и в соответствии с корпоративным стандартом для выпуска продукта в розницу. Документы как таковые и описания макетов при этом создаются и хранятся раздельно.
Публикация документа в разных электронных форматах. Описания продуктов размещаются на веб-сайте в формате HTML и передаются типографии для тиражирования в формате PostScript. Многоплатформенное решение может комплектоваться документацией в форматах, специфичных для разных сред: СНМ для Microsoft Windows и man pages для Unix. Другой типичный случай - создание руководства пользователя и файла помощи (*.Ыр) на основе одного и того же текста.
Автоматизация компоновки документов. Устранение физического дублирования текста при сохранении его вхождений в разные документы. Условный текст, в том числе, профилирование текста по
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
239
аудитории, платформам, операционным системам. Автоматизированное формирование структур документов.
Создание функциональных электронных документов. В основном это веб-публикации с развитыми средствами навигации и поиска, базы знаний наподобие MSDN.
Формирование информационно-поискового аппарата. К информационно-поисковому аппарату относятся оглавления, всевозможные указатели, перекрестные ссылки и т.п. В комплект, состоящий из нескольких документов, полезно включать объединенное оглавление и объединенный предметный указатель. Также бывают необходимы перекрестные ссылки между документами. Реализация этих возможностей средствами обычных текстовых процессоров отнимала бы у авторов слишком много времени.
Интеграция документирования с разработкой. Будучи связаны административно, эти процессы нередко полностью изолированы друг от друга технологически. Управление требованиями, управление конфигурациями, контроль версий, трассировка ошибок для технической документации и документируемого решения выполняются параллельно. Дублирование функций не экономично и неудобно. Кроме того, документы и программы могут иметь общие компоненты, например, тексты сообщений, которые и отображаются в интерфейсе пользователя, и упоминаются в документации. Очевидно, разработчики могут время от времени редактировать их, поэтому, если не сделать соответствующий ресурс общим, то придется постоянно сверять документацию с программой.
3.3.2.	Основные понятия и определения
Выходным будем называть электронный документ, который поставляется пользователю. Случай, когда пользователь работает с твердой копией, даже если это книга, отпечатанная в типографии, не рассматривается как отдельный, потому что твердая копия производится на основе электронного документа.
Формат файла выходного документа называется целевым.
Внешний вид, графическое оформление выходного документа будем называть макетом. В общем случае оформление документа не обязательно должно быть графическим.
240 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
Рис. 3.3. Формирование выходного документа
Набор правил построения макета называется принципиальным макетом. Свойства принципиального макета и технические свойства выходного документа, связанные с целевым форматом (например, средства навигации в PDF-файле), обобщенно будем называть оформлением.
Взятую отдельно смысловую часть документа, т.е. выходной документ за исключением оформления, будем называть входным документом.
Если входной документ и данные об оформлении хранятся раздельно, то выходной документ формируется в результате определенного преобразования (рис. 3.3). Преобразование может представлять собой цепочку преобразований, выполняемых друг за другом. Тогда каждое из них, кроме последнего, формирует промежуточный документ, который подается на вход следующему в цепочке (рис. 3.4). При этом каждое преобразование может использовать относящуюся именно к нему часть данных об оформлении. Как уже не раз говорилось ранее, большие объемы технической документации разрабатываются не в одиночку и не сразу. Поэтому единый источник не сводится к чистой технологии, это еще и определенный способ организации работы специалистов, участвующих в документировании. Всех, кто составляет текст технической документации, будем называть авторами. При этом, говоря о тексте, будем иметь в виду и собственно текст, и относящиеся к нему материалы, в том числе, рисунки. Авторами могут быть не только профессиональные технические писатели, но и специалисты, для которых документирование только одна из их функций.
Принципиальный макет либо создается дизайнером, либо продиктован одним из стандартов. Технически оформление реализуется про-
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
241
Рис. 3.4. Цепочка преобразований
граммистом. Он умеет описывать принципиальные макеты тем способом, который понятен программам, выполняющим преобразования.
Автора, ответственного за успех подготовки документов, будем называть редактором (он руководит авторами, но о его функциях и полномочиях разговор отдельный). Предположим, что документирование проводится в рамках некоторого проекта. У проекта обязательно есть заказчик, он может быть внутренним или внешним по отношению ко всей организации, но по отношению к самому проекту он в любом случае внешний. Заказчик диктует требования к технической документации, причем некоторые из них, например, соответствие документов определенному стандарту, подлежат безусловному выполнению. «Бесконечную» деятельность по развитию некоторого технического решения (автоматизированной системы, программного продукта) будем рассматривать как серию проектов.
3.3.3.	Содержание, структура, оформление
Единый источник вне зависимости от его технической реализации содержит все фрагменты, которые могут быть включены в разрабатываемые документы. Объем фрагмента определяется его предполагаемой функцией, фрагментом может быть целая глава, а может ячейка таблицы. Обычно от фрагментов, несущих одну функцию, требуют единообразной структуры, например, все функции API должны быть описаны по одному плану.
242 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
ФРАГЖ14Г-К

Рис. 3.5. Древовидная структура ПС
Для каждого фрагмента в едином источнике должна храниться ровно одна копия. Фрагмент обязательно снабжается уникальным идентификатором, по которому к нему можно получить доступ. Допускается выделение внутри фрагмента других фрагментов. Последнее не означает, что фрагмент, содержащий другие фрагменты, целиком из них состоит, просто его частям, представляющим самостоятельный интерес, присваиваются уникальные идентификаторы.
В крупных проектах фрагменты чаще образуют лес1, а не дерево (рис.??). Фрагменты, не загружаемые в источник, являются отдельными компонентами связности, не соединенными ребром с корнем дерева (источником). Последовательность разработки фрагментов и их загрузки в единый источник не имеет значения. Не существенен и способ хранения фрагмента, такие детали, как число и взаимное расположение XML-файлов, которыми представлен фрагмент, должны касаться только его автора.
Шаблон документа задает структуру его разделов и состав включаемых в него фрагментов. Кроме заголовков и метаданных шаблон не содержит собственного текста. Его место занимают включающие ссылки на фрагменты единого источника. Включающая ссылка может явно указывать на фрагмент с определенным значением уникального идентификатора или содержать запрос на выборку фрагментов, удовлетворяющих определенным условиям. Применительно к текстовым процессорам шаблоном обычно называют образец оформления любых
1 Многосвязный ациклический граф. Граф, в котором каждая компонента связности является деревом.
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА	243
документов некоторого типа, например, в поставку текстового процессора Microsoft Word входят шаблоны писем, резюме, служебных записок и даже технической документации. В нашем случае у каждого конкретного документа должен быть свой шаблон, причем к оформлению он как раз не имеет отношения.
Шаблон и все фрагменты, на которые он прямо или косвенно ссылается, в совокупности составляют входной документ.
В общем случае структура входного документа глубже структуры шаблона, потому что любой фрагмент может иметь собственную структуру.
Таким образом, каждый документ можно разложить на три обязательных составляющих: содержание, структуру и оформление. Назвать эти составляющие абсолютно независимыми друг от друга было бы преувеличением, но выделить разработку каждой из них в самостоятельную задачу внутри проекта, как правило, возможно.
Это дает разработчику следующие преимущества.
•	Содержание и структура изолированы от оформления. Их можно разрабатывать параллельно, сокращая критический путь проекта. Кроме того, модификация одной из этих составляющих никогда не приводят к сбоям в другой: авторы заведомо не испортят оформление, а оформитель - текст.
•	Разработка содержания легко распределяется между несколькими авторами. При обновлении фрагментов не требуется повторно вставлять их во входной документ. Если фрагмент входит в несколько входных документов, то расхождения между последними по этому фрагменту заведомо исключены.
•	Полученные результаты можно использовать многократно. Из одних и тех же выверенных фрагментов можно формировать документы, предусмотренные ГОСТ, RUP или MSF. Одни и те же документы можно оформлять по-разному и распространять в разных форматах. Одни и те же отлаженные правила оформления можно использовать для разных документов и даже в разных проектах и т.д.
Таким образом, в документировании, как и в программировании, изоляция участков работы и повторное использование отлаженных результатов обеспечивают устойчивость ка-
чества.
244 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
3.3.4.	Единый источник как база знаний
Атрибутизация фрагментов и создание механизмов их поиска по значениям полей позволяет рассматривать единый источник как базу данных. Тогда выходной документ можно сравнить с отчетом, а шаблон документа - с формой отчета. Поля могут содержать данные об аудитории, теме или состоянии фрагмента. Например,
•	фрагмент помечают как адресованный только квалифицированным или только начинающим пользователям,
•	как относящийся только к определенной версии продукта,
•	как завершенный или незавершенный.
Также в поля можно выносить важные сведения о предмете описания, разумеется, когда их удается формализовать. Например, если фрагмент говорит о некоторой функции автоматизированной системы, то в специальное поле можно поместить список пользовательских ролей, которые к этой функции обращаются.
Атрибутизация фрагментов позволяет:
•	профилировать документы по разным признакам;
•	организовать проблемно-ориентированный поиск;
•	организовать проблемно-ориентированную навигацию.
Профилированием называется автоматический отсев фрагментов по заданным признакам при формировании выходного документа. Обычно профилирование применяется, когда необходимо подготовить несколько редакций одного и того же документа для разных аудиторий, причем различия между редакциями заключаются во множестве небольших по объему фрагментов, касающихся важных деталей. Например, руководство пользователя адресовано и службе технической поддержки, и конечным пользователям, но последних лучше не знакомить с особенностями защиты от копирования или редко возникающими проблемами. Другой типичный случай профилирования - руководства по приложениям, имеющим параллельные версии для разных аппаратных платформ и операционных систем. Встречается профилирование по последовательным версиям самого документируемого решения, если эти версии выпускаются часто и отличаются друг от друга незначительно.
Проблемно-ориентированный поиск обеспечивает пользователю возможность быстро ориентироваться во взаимосвязях между частями или свойствами технического решения. Распространенный при
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
245
мер проблемно-ориентированного поиска - размещаемый в конце каждого раздела список перекрестных ссылок на ассоциативно связанные разделы, обычно он имеет подзаголовок «См. также». Такие списки могут формироваться авторами вручную, а могут автоматически по общим для связываемых разделов ключевым словам. К средствам проблемно-ориентированного поиска мы относим указатели специального вида, например, указатель функций API в руководстве программиста или указатель первичных документов в руководстве по ERP-системе.
Проблемно-ориентированная навигация не только позволяет быстро найти нужные сведения, но и сама по себе информативна. Если техническое решение состоит из большого количества компонент, то можно построить , схему, иллюстрирующую характер взаимосвязей между ними, допустим, дерево зависимостей или диаграмму потоков данных, снабдив каждый элемент этой схемы гипертекстовой ссылкой на соответствующий раздел. Если система автоматизирует какой-нибудь бизнес-процесс, то можно построить диаграмму бизнес-процесса, разметив ее гипертекстовыми ссылками на технологические инструкции по выполнению отдельных операций.
Перечисленные возможности в совокупности позволяют обращаться с единым источником как с базой знаний о техническом решении. Поддержание полноты и актуальности базы знаний выходит на первый план, а формирование выходных документов становится вспомогательной задачей, быстро решаемой в случае необходимости.
3.3.5.	Технологическая платформа DocBook/XML
Проблема унификации форматов данных, вероятно, возникла вместе с первыми ЭВМ, это «родовая травма» информационных технологий. Противоборствуют две тенденции: с одной стороны, каждая задача требует средств обработки и хранения специфичных для нее данных, с другой стороны, необходимость обмена данными требует эти средства унифицировать. Поиски разумного компромисса на этом поле время от времени приводили к появлению более или менее удачных универсальных форматов. В основном они предназначались для представления данных определенного характера: графики, текста, звука, географических карт, баз данных и т.п. Поскольку разработчики действовали разрозненно, форматы не только получались разными, но и
246 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
в основе имели разные принципы организации данных. Приходилось для каждого формата разрабатывать отдельные механизмы обработки, что не экономично само по себе и вдвойне не экономично, если в одном приложении обрабатываются данные разных форматов.
Вряд ли кто-нибудь строил иллюзии относительно возможности разработки универсального, энциклопедического формата, пригодного для представления любых мыслимых данных. Выходом из положения виделось создание абстрактного формата форматов, который позволял бы описывать сколь угодно специфичные форматы, но такие, чтобы синтаксическое родство между ними было достаточно сильно и допускало реализацию общих механизмов обработки. В качестве решения этой задачи в 1989 г. был предложен язык Standard Generalized Markup Language (SGML), а позже, в 1998 г., более простой и технологичный extensible Markup Language (XML).
XML - это язык описания языков разметки с общим синтаксисом и разными словарями. С нобода словаря позволяет создавать конкретные специализированные XML-языки, а общность синтаксиса - обрабатывать произвольные XML-данные одними и теми же программами. Для ввода данных можно использовать любой XML-редактор, а для публикации на веб-сайте любой XSLT-процессор. Одновременно имеется возможность автоматически загружать данные в базу данных и находить там нужные сведения по существенным для предметной области признакам.
Хороший принцип в сочетании с удачной реализацией привели к взрывообразному росту XML-технологий. Количество программ для работы с XML-данными и специалистов, владеющих этой областью, увеличивается ежедневно. Во многие прикладные пакеты встраивается возможность импорта и экспорта XML-данных.
Основой технологической платформы DocBook/XML служит одноименный проблемно-ориентированный язык разметки [6]. Он предназначен для записи текста технической документации на программы, алгоритмические языки, компьютерное оборудование и другие решения в области информационных технологий, чем принципиально отличается от большинства форматов хранения текстовых данных (но не XML-языков!). В языке DocBook/XML предусмотрены средства описания фрагментов, свойственных технической документации, например, специальными элементами полагается выделять названия элементов интерфейса, обозначения клавиш, имена переменных, термины, раз
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
247
личные врезки (замечания, подсказки, предупреждения), листинги, описания выполняемых пользователем процедур.
Разметка, задаваемая языком DocBook/XML, носит преимущественно функциональный характер: автору предписано указывать роль, которую тот или иной фрагмент играет в тексте, а не способ его внешнего оформления. Такой подход сковывает автора, зато позволяет добиться заведомой независимости содержания и оформления выходного документа и унифицировать некоторые важные качества стиля изложения при работе нескольких авторов в одном проекте.
Язык разметки DocBook имеет долгую по «компьютерным» меркам историю. Его первая версия, опиравшаяся на SGML, была создана еще в 1991 г. совместными усилиями компаний O’Reilly & Associates и HaL Computer Systems. Версия на базе XML увидела свет в 1998 г., тогда же язык перешел в ведение специально образованного технического комитета консорциума OASIS. В состав этого технического комитета входят всемирно известные компании, в том числе, Hewlett-Packard и IBM. Сегодня язык разметки DocBook/XML применяется разработчиками технической документации во всем мире.
Многообразие языков разметки невероятно велико. Так, для векторной графики существует язык SVG, для математических формул MathML, для отформатированного текста XSL-FO; перечислять здесь все языки разметки нет ни возможности, ни надобности. Все они складываются в открытую технологию, допускающую решение любой осмысленной задачи за соразмерное время при соразмерных затратах. В этом их преимущество перед проприетарными продуктами, которые могут предоставлять богатые возможности, но не допускать выхода за их пределы.
3.3.6.	MadCap Flare: система для разработки технической документации на основе единого источника
MadCap - американская компания, на рынке существует достаточно давно, но, к сожалению, практически не известна в России.
Flare - программа, предназначенная для создания и организации содержания, которое впоследствии можно использовать и для печати, и для публикации на сайте. На сегодняшний день это единствен
248 3, ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
ный продукт, позволяющий относительно безболезненно взаимодействовать с Adobe FrameMaker, на котором идет весь основной поток документации компании [20]. Стоимость продукта - 999$ [35].
MadCap Flare - профессиональный комплекс, предназначенный для технических писателей и специалистов по составлению документации, позволяющий создавать, редактировать и публиковать разработанные материалы как на бумаге, так и в интернете. MadCap создает документы как в формате PDF, так и в форматах файлов онлайн-помощи: WebHelp и WebHelp Mobile.
Программа имеет возможность отображения одного и того же файла в разных видах [20]:
•	для печати;
•	в виде для публикации на сайте;
•	в виде источника XML.
При запуске программы Flare можно начать работу с новым проектом, или импортировать уже существующий проект, или посмотреть работу программы на примере уже созданного проекта. Возможность генерации различных выходных файлов реализована в виде списка так называемых тагетов. По умолчанию - это стандартный список, но его можно редактировать по желанию пользователя.
Сборка выходного файла осуществляется с помощью команды Build, и впоследствии любой сгенерированный выходной файл доступен для просмотра с помощью команды View из меню по правой кнопке мыши.
При использовании Flare запускается визуальный редактор XML текстов, так что, пользователи могут применять все преимущества и достоинства языка XML без обязательных знаний этого языка. Таким образом, автору достаточно корректно собрать только оглавление своего документа, остальное будет выполнено программой.
Данный продукт обладает и возможностью создания различных документов из одного и того же набора исходных файлов путем использования различных структур (называемых ТОС).
Содержание (Table of Contents, ТОС) может формироваться из любого количества файлов в любом порядке, и количество содержаний не ограничено. В новое только что созданное содержание файлы можно <перетаскивать» из Content Explorer и расставлять по порядку и по иерархии. Если содержание сгенерировано автоматически в процессе импорта, придется каждому элементу поставить в соответствие файл.
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
249
Это не составляет проблем, т.к. все элементы содержания, не имеющие привязанных к ним файлов, помечаются красным.
Все изменения в содержимом выполняются в соответствии с единым источником и обновляются в проекте для каждого конкретного типа документации. Авторы проекта могут создавать и собственное форматирование, несмотря на различные шаблоны. Программа предусматривает поддержку технологии drag-and-drop для быстрого редактирования текста.
Редактирование содержимого в Flare может осуществляться в двух разных режимах - Web для использования в Интернете и Print для форматирования на печатном листе с полями, отступами, заголовками, сносками и пр. для вывода на бумагу.
Flare позволяет упростить процесс импорта документов в новую основанную на XML среду. Возможен импорт из таких программ как Adobe©RoboHelp, Adobe©FrameMaker©, Microsoft©Word, .CHM, DITA и многих других [35]. Для этого не требуется никаких дополнительных знаний. Заметим, что среди перечисленных форматов есть и кросс-платформенные, печатные форматы, онлайн-помощь, оптимизированная под мобильные устройства...
С помощью Flare гораздо проще документировать сложные проекты: легко можно расставлять тэги заголовков, файлов, папок и прочих объектов, находящихся в области зрения Flare. Собрав эти тэги, в дальнейшем можно будет получить полностью готовый документ, который на них базируется.
Программа Flare позволяет полностью управлять создаваемым текстом, напрямую интегрируясь и получая доступ к таким программам как Microsoft SharePoint. Более того, существует немало программного обеспечения, например, Subversion, Microsoft Team Foundation и Visual Source Safe, которое напрямую интегрируется с Flare и получает доступ к информации, созданной Flare. Это позволяет эффективно вести корпоративную разработку ПО любой степени сложности. Внешние ресурсы Flare позволяют отслеживать и обмениваться файлами любого числа проектов и с любым числом пользователей.
Функции и возможности MadCap [20]:
•	поддерживаются любые языки, в том числе, восточные и русские;
•	один и тот же текст в одном и том же формате можно представлять в разном оформлении (использование функции Skin);
250 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
•	есть возможность загружать файлы из системы управления изменениями (например, Visual SourceSafe);
•	есть возможность загрузки собранного проекта на ftp-сервер или на корпоративный сайт непосредственно из Flare, для этого используется директория Destinations;
•	создание списков иллюстраций, таблиц, других элементов;
•	создание отчетов по ошибкам, например, анализ неработающих ссылок или случайно пропущенных и не вошедших в оглавление топиков;
•	использование единых переменных для проекта (Variables);
•	широкая поддержка графики (включая .xps, .xaml, .wmf, ,emf);
•	возможность одновременного просмотра и редактирования нескольких документов.
•	и многое другое.
К недостаткам данного программного продукта относятся следующие [20].
•	Импорт из Frame Maker далеко не так идеален, как хотелось бы. Например, при импорте из FrameMaker забирается не исходная картинка, а ее изображение. Фактически, файл для импорта собирает Distiller. Также при импорте теряется форматирование страниц. Показательный факт: описание процедуры оптимизации импорта проектов FrameMaker в Flare опубликован на официальном сайте программы, и оно занимает 40 страниц.
•	Flare - это в первую очередь XML-редактор. Обладая знаниями хотя бы основ HTML и XML, работать с документами гораздо проще. Это не было бы недостатком, если бы создатели программы не ставили в число основных достоинств своего детища то, что оно не требует знания XML для работы с ним.
Существуют и другие продукты линейки MadCap, которые могут пригодиться при написании технической документации и создании презентаций:
•	MadCap Lingo - программа, очень полезная для переводов и локализации руководств пользователя. Содержит, например, встроенный автоматический переводчик (русско-английский словарь для которого можно бесплатно скачать на сайте MadCap).
•	MadCap Mimic - средство для создания обучающих фильмов и презентаций. В частности, при скачивании Trial к MadCap Flare,
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
251
удается получить в комплекте шесть уроков для начинающих, созданных как раз на базе Mimic.
•	MadCap Feedback - готовое решение для организации обратной связи с пользовательского сайта. Например, вся активность пользователей выводится в виде статистических отчетов (ключевые слова, самые интересные темы, а также темы, которые никому не интересны), есть возможность для пользователей писать свои комментарии к темам и обращаться к разработчикам напрямую.
Список корпоративных пользователей программы MadCap Flare приведен на официальном сайте [35].
3.3.7. Arbortext: система разработки, генерации и публикации технической документации
Arbortext [23] - семейство продуктов американской компании-гиганта PTC (Parametric Technology Corp.), предназначенное для создания технической документации. В своей основе Arbortext использует принцип единого источника, в основе которого лежит формат XML. Рассмотрим более подробно Arbortext Editor with Styler, который является основным инструментом технического писателя [9].
Данный продукт позволяет:
•	повысить производительность процесса разработки документации;
•	сократить затраты на разработку, перевод и публикацию;
•	повысить точность, полноту и надежность информации;
•	ускорить время выпуска изделия на рынок.
Arbortext использует всю мощь языка XML, чтобы избежать ручных усилий и излишней информации, упростить и автоматизировать процесс публикации. В результате удается снизить себестоимость и время выпуска публикаций, одновременно повысив качество и точность пользовательской информации. Arbortext - единственное законченное решение в области корпоративных публикаций - предоставляет полную поддержку процесса публикации информации предприятия от создания до выпуска [27].
Линейка Arbortext включает в себя следующие продукты [9].
252 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
Arbortext Editor - мощный XML редактор, интегрируемый с другими продуктами компании РТС (в числе которых база данных CSDB for S1000D, система PLM Windchill и т.д.). Поддерживает многочисленные форматы выходных публикаций, такие как Web, PDF, HTML Help, Digital Media Publisher.
Arbortext Styler - надстройка, интегрированная в Arbortext Editor, позволяющая с помощью визуального интерфейса легко создавать и редактировать стили, применяемые при публикации XML источника в различные форматы. Очень часто Arbortext Editor выбирается именно в комплектации Arbortext Editor with Styler.
Arbortext ISO Draw - система для создания технических иллюстраций. Arbortext IsoDraw автоматизирует процесс создания высококачественных 2D и 3D технических иллюстраций и анимаций прямо из трехмерных моделей. Иллюстрации автоматически обновляются при изменении исходных моделей САПР.
Arbortext Publishing Engine - сетевой сервер для публикации. Позволяет подбирать и публиковать материал в соответствии с выбранными требованиями содержания и формата. Содержит машину для публикации в формат IETP.
Arbortext Content Manager. Предназначен для управления содержательной частью документов и является частью системы динамических публикаций фирмы PTC (PTC Dynamic Publishing System). Он позволяет использовать единый источник информации, обеспечивает управление компонентами системы на всех уровнях, отслеживает связи между ними, и предоставляет возможность настраивать конфигурацию системы. Все это оптимизирует процессы подготовки и выпуска информационных изданий силами предприятия.
Arbortext Architect. Позволяет разрабатывать и редактировать схему и структуру документов (DTDs - Document Type Definitions) под индивидуальные требования к издаваемой информации.
Arbortext Dynamic Link Manager. Позволяет создавать связи между частями документов и управлять ими.
Arbortext Digital Media Publisher. Позволяет подготавливать файлы и каталоги к изданию в различных цифровых форматах.
Arbortext CSDB for S1000D (Arbortext ASD WOOD) является полностью настроенным решением «под ключ», реализующим техническую документацию в соответствии со спецификациями ASD 1000D и ASD 2000М.
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
253
Высокая степень интегрированности продуктов Arbortext с другими продуктами РТС позволяет осуществлять разработку документации не просто в XML редакторе, но в специальной среде разработки [9]. Эта среда дает возможность не только создавать XML, но и хранить документацию, создавать интерактивные иллюстрации, организовывать параллельную работу по созданию документации нескольким участникам процесса, в то время как большинство редакторов -замкнутые решения для локального пользователя, нацеленные больше на какие-то свои изыски, но не на законченное решение.
Функциональность самого редактора ArborText Editor, которая будет подробно рассмотрена далее, отвечает всем современным требованиям для организации профессиональной работы по разработке документации - с одной стороны. С другой стороны, Arbortext Editor создан для того, чтобы скорее начать работу и получить результат, не нуждаясь в специфических знаниях о XML, XSL-FO, тонкостях инсталляции стандартов, типов документов и т.д.
Практически всегда документация разрабатывается не с чистого листа. Многие понимают, что при переходе на использование единого источника данных в формате XML потребуется не только организовать разработку документации, но при этом использовать имеющиеся наработки. Arbortext содержит конфигурируемый модуль для импорта данных из Microsoft Word и Adobe FYameMaker в формат XML.
Начав работу и решив создать новый документ, сразу же отображается список предустановленных типов документов ВЕВ: DITA, DocBook/XML, SMA (service manual application - специализация на основе DITA) и другие. Нет необходимости устанавливать или настраивать DITA или DocBook. Достаточно указать новый тип документа (DTD).
Выбор пункта Sample позволяет открыть предустановленный пример документа того или иного типа для ознакомления. Заполненные атрибуты тегов по умолчанию отображаются с их значениями в значках тегов разметки, что довольно наглядно, так как не нужно просматривать окно атрибутов каждого тега.
Arbortext Editor может включать функцию импорта документов различных форматов в формат XML.
Для импорта используется специальный шаблон STD. Можно использовать готовые шаблоны, а можно воспользоваться встроенным редактором.
254 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
В данной программе удобно создавать профилирование документов. Заполняя атрибуты элементов (например, разделов) и привязывая их к некоторому профилю можно впоследствии просматривать или публиковать информацию, предназначенную для специализированной аудитории.
При публикации для любого профиля вся нумерация параграфов и заголовков будет пересчитана в рамках нового документа и автоматически будет сформировано новое оглавление.
Профили для каждого документа хранятся в файле и размещаются в каталоге с DTD. Имеется возможность создания файла профилей в среде Editor, опять же, не прибегая непосредственно к кодированию.
Помимо файла профилей PCF можно аналогичным образом создать файлы навесок и настроек, применительно к данному типу документа.
Файл переименований .alias используется, если требуется, чтобы теги XML в интерфейсе Arbortext Editor назывались по-другому. Например <рага> может отображаться как Параграф, <li> как Следующий пункт. Полезная возможность, когда необходимо предложить работу в Editor человеку, который ранее не был знаком с HTML/XML, но привык к работе в Microsoft Word.
В файле настроек .DCF (document type configuration) можно в рамках определенного типа документа настраивать функциональность панели инструментов, пользовательские словари, автоматическую вставку одних тегов вокруг других, запрещать редактирование/скрывать определенные атрибуты или теги и многое, многое другое.
Файл применяемых стилей публикации создается в Arbortext Styler.
ArborText Styler - эффективная опция Arbortext Editor, позволяющая создавать в визуальном редакторе собственные стили публикации во все форматы, применяемые к XML источнику. Styler пользуется уже созданными стилями XSL-FO, либо формирует свои стили в формате fosi, xsl-fo или родном формате с расширением .style.
Styler обеспечивает быстрое создание и модифицирование таблиц стилей для преобразования содержимого документов XML в различные форматы данных.
Обозначим некоторые возможности Styler [9].
3.3. ТЕХНОЛОГИЯ ЕДИНОГО ИСТОЧНИКА
255
Стиль охватывает все элементы DTD и дает возможность стилизовать не только каждый элемент DTD в отдельности, но и формировать.
•	Вставка генерируемого текста. Некоторый текст до и после некоторых элементов выделяется цветом (по умолчанию - синим) и недоступен для редактирования. Это значит, что он генерируется автоматически. С помощью генерируемого текста, например, формируется содержание, подписи под рисунками, автоматическая нумерация глав и списков, расстановка символа копирайта и т.Гд.
•	Наследование - когда элементу принудительно не заданы некоторые параметры (отступ, шрифт и т.д.), он наследует их от родителя.
•	Контекстные условия - можно стилизовать отдельно параграф, отдельно параграф в главе, отдельно параграф в параграфе и т.д.
•	Условия проверки атрибутов и содержимого. Можно стилизовать элементы по-разному, в зависимости от заданных атрибутов и сожержимого.
•	Возможность в рамках одного стиля задавать некоторые нюансы, которые будут применимы только для PDF, только для Web, только для Help и т.д.
Помимо перечисленного, Styler содержит свою панель для публикации и предпросмотра документов, поддержку языка XPath.
Для формирования единой среды разработки документации и обеспечения поддержки жизненного цикла документации предусмотрены следующие программы [9].
Arbortext CSDB for S1000D является средой <под ключ» разработки, создания, управления и эксплуатации технических публикаций.
Система обеспечения жизненного цикла изделий Windchill. Являясь веб-ориентированной PLM системой, где клиентом является обычный Internet Explorer, Windchill формирует среду для хранения данных и разработки изделия, обеспечивает полноценный workflow. Windchill особенно незаменима, когда участники проекта удалены друг от друга, но имеют доступ к локальной или глобальной сети. Пользователь может сформировать правила, по которым загружаемые XML документы будут разбиваться на несколько файлов, превращаясь в
256 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
сборку для формирования параллельной работы удаленных пользователей и формирования книг на основе повторного использования частей документации.
В России продукты Arbortext широко применяются на предприятиях авиационной промышленности. Клиентами компании PTS (Продуктивные Технологические Системы) уже стали АО НПО «Иркут», ОАО «Туполев», НПО «Сатурн», ОКБ им. А.С. Яковлева, ТАНТК им. Бериева, ГП Киевский Авиационный Завод «Авиант», ЦСКБ «Прогресс» [91-
3.4. Издательская система
ГХЩХ [36] - это макропакет, позволяющий авторам верстать и печатать работы с высоким типографическим качеством при помощи заранее определенных профессиональных макетов. В качестве механизма для верстки он использует TfeX, компьютерную программу, созданную Дональдом Кнутом в 1977 году для верстки текста и математических формул. Первая версия была выпущена Лесли Лэмпортом в 1984 году; текущая версия, Ш^Х2е, после создания в 1994 году испытывала некоторый период нестабильности, окончившийся к концу 90-х годов, а в настоящее время стабилизировалась (хотя раз в год выходит новая версия).
UT^X - свободное ПО, доступен на условиях UTgX Project Public License (англ.) (LPPL). LPPL не совместима c GNU GPL, так как она требует, чтобы измененные файлы были явно различимы с оригиналами (обычно, имели другие имена); это было сделано для уверенности, что зависимости между существующими файлами не будут нарушены и чтобы избежать проблем с совместимостью.
Для того чтобы опубликоваться, авторы отдают свои рукописи в издательство. Затем один из дизайнеров издательства определяет макет документа. В среде I^T^X сама программа берет на себя роль дизайнера книги, используя Т^Х в качестве верстальщика. Например, данное учебное пособие сверстано с помощью . Но ЕСЦеХ - всего лишь программа, и, следовательно, нуждается в более четких инструкциях. Автор должен предоставить дополнительную информацию, описывающую логическую структуру своей работы. Эта информация записывается в текст в виде команд.
3.4. ИЗДАТЕЛЬСКАЯ СИСТЕМА HTfeY
257
Такой подход очень сильно отличается от концепции, принятой в большинстве современных текстовых процессоров (таких как MS Word). В этих приложениях авторы формируют документ интерактивно в процессе набора текста на компьютере. В процессе работы они могут видеть на экране как будет выглядеть их работа, когда, в конце концов, она будет напечатана.
При использовании обычно невозможно увидеть итоговую картину во время печатания текста. Ее, однако, можно посмотреть на экране после обработки файла Затем можно внести все необходимые изменения.
Основные преимущества Ш£Х перед обычными текстовыми процессорами:
1)	готовые, профессионально выполненные макеты;
2)	удобно поддержана верстка математических формул;
3)	пользователю нужно выучить лишь несколько понятных команд, задающих логическую структуру документа, ему практически никогда не нужно возиться собственно с макетом документа;
4)	легко изготавливаются даже сложные структуры: примечания, оглавления, библиографии и пр.
5)	для решения многих типографских задач, не поддерживаемых напрямую базовым Ш^Х, есть свободно распространяемые дополнительные пакеты;
6)	поощряет авторов писать хорошо структурированные документы, т.к. именно так и работает;
имеет также и некоторые недостатки, но среди них не найдется ни одного существенного. Например, несмотря на то, что многие макеты имеют множество настраиваемых параметров, создание полностью нового макета документа не очень просто и занимает много времени. Также очень сложно писать неструктурированные и неорганизованные документы.
Исходными данными для являются обычные текстовые файлы, которые можно создать в любом текстовом редакторе. Эти файлы содержат текст документа вместе с командами, указывающими LMfeX, как верстать текст.
Как уже говорилось выше, термин относится только к языку разметки, он не является текстовым редактором. Для того, чтобы создать документ с его помощью, надо набрать .tex файл с помощью какого-нибудь текстового редактора. В принципе, подойдцт любой редактор,
258 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
но большая часть людей предпочитает использовать специализированные, которые так или иначе облегчают работу по набору текста DTf>X-разметки.
В последнее время стали широко распространены редакторы, позволяющие легко создавать текстовые файлы и снабжать их командами с помощью выбора их из некоторого меню или списка. Эти программы имеют простой и понятный интерфейс, они не только позволяют создавать и сохранять файлы с помощью подстановки заготовленных команд и шаблонов форматирования, но и формировать оригинал-макет посредством вызова программы-транслятора. К таким редакторам относятся, например, свободно-распространяемый TeXnicCenter [38] и условно бесплатный WinEdt [39]. Полный список редакторов приведен, например, в [21]. В результате обработки файла программой-транслятором получим файл с расширением *.dvi (device independent - не зависящий от устройства). Этот файл можно просмотреть и распечатать с помощью программ, называемых dvi-драйверами. Например, это можно сделать с помощью программы уар.ехе (Yet Another Pre viewer), входящей в состав пакета MikTeX [36]. В последних версиях трансляторов появилась возможность формировать результирующий файл с расширением *.pdf.
Возможности системы практически не ограничены благодаря механизму программирования новых макросов. Имеется внушительный список стандартных макросов и различных надстроек и расширений, которые можно скачать с сервера CTAN [34]. Само название CTAN является аббревиатурой Comprehensive Archive Network (всеобъемлющая сеть архивов ). Среди этих макросов и расширений присутствуют следующие:
•	алгоритмы расстановки переносов, определения междусловных пробелов, балансировки текста в абзацах;
•	автоматическая генерация содержания, списка иллюстраций, таблиц и т.д.;
•	механизм работы с перекрестными ссылками на формулы, таблицы, иллюстрации, их номер или страницу;
•	механизм цитирования библиографических источников, работы с библиографическими картотеками;
•	размещение иллюстраций (иллюстрации, таблицы и подписи к ним автоматически размещаются на странице и нумеруются);
3.4. ИЗДАТЕЛЬСКАЯ СИСТЕМА WlfiX
259
•	оформление математических формул, возможность набирать многострочные формулы, большой выбор математических символов;
•	оформление химических формул и структурных схем молекул органической и неорганической химии;
•	оформление графов, схем, диаграмм, синтаксических графов;
•	оформление алгоритмов, исходных текстов программ (которые могут включаться в текст непосредственно из своих файлов) с синтаксической подсветкой;
•	разбивка документа на отдельные части (тематические карты). Расширенные средства работы с библиографическими данными предо-стяклякггся программой Bibl^X. Базовые возможности работы с математическими формулами расширяются с помощью пакета AMS-LMfeX, разработанного американским математическим сообществом. Набор AMS- предоставляет дополнительные математические символы, множество удобных возможностей для оформления математических формул (например, упрощенную работу с многострочными формулами) и используется почти во всех Ш^Х-документах, в которых есть сколько-нибудь сложные формулы.
Документ - это текстовый файл, содержащий специальные команды языка разметки. Сам документ делится на преамбулу и тело. В преамбуле содержится информация о классе документа, использованных пакетах макросов, определениях макросов, авторе, дате создания документа и пр. Тело документа содержит собственно текст документа и команды разметки. Оно должно находиться между командами Примеры написания преамбулы и некоторых команд тела документа приведены в 121]. Одним из самых подробных руководств по верстке в системе на русском языке является [4].
Во многих развитых компьютерных аналитических системах, например, Maple, Mathematica, Maxima возможен экспорт документов в формат *.tex. Для представления формул в Википедии также используется Т^Х-нотация. При наборе формул в MS Word с помощью MathType также возможен экспорт в T£X. Более того, в последнее время появилось немало утилит, экспортирующих документы Word в СЩХ (например, Word2Tex).
Данная издательская система используется не только для верстки текста, но и для подготовки презентаций. Класс для I^IfeX, позволяющий создавать слайды для презентаций, называется Beamer. Этот
260 3. ПАКЕТЫ ПРОГРАММ ДЛЯ ФОРМИРОВАНИЯ ОТЧЕТОВ
~ ’ ...... . ... . .
The necessary and Sufficient Condition of Compatible Trail Existence
Graphs by Trails with Local Restrictions
PtMiyukwa.
The Problem
Theorem (A. Kotzig)
Connected Eulerian graph G has Po-campadble Eulerian trail if and ixdy if
(Vv € V) (Ур € Pa(v)) (|р| <	•
Obviously, complexity atchecking the condition of existence of PG-oompatihh Eulerian trail is not more thanO(|i?(G)|).
puth
Algorithm
T(2 comps Path
Edges
Algorithm compatible
Eulerian Trail
Algorithm
COVERING BY T<; A LI OWED TRAILS
1
Рис. 3.6. Пример слайда, выполненного с помощью beamer
класс позволяет включать сложные математические формулы, иллюстрации, анимацию. Вообще говоря, Beamer - далеко не первый класс LaTeX для создания презентаций, и, как многие его предшественники он имеет специальный синтаксис для определения < слайда» (в Beamer он называется frame) [37].
Презентации имеют четко выраженную структуру (так как создаются с помощью и содержат структурные единицы: разделы, параграфы, списки), по которой удобно ориентироваться и перемещаться во время презентации. Кроме того, так как имеет огромные возможности для написания математических формул, Beamer представляет пользователю всю мощь для создания научных презентаций.
Внешний вид слайда, созданного с помощью этого пакета приведен на рис.3.6. В [37] приведены ссылки на учебные материалы и прочие ресурсы, посвященные классу Beamer.
Литература
1.	Липаев,	В. В. Документирование сложных программных
средств/В.В. Липаев. - М.: СИНТЕГ, 2005. - 135 с.
2.	Липаев, В,В. Обеспечение качества программных средств. Методы и стандарты/В.В. Липаев. - М.: СИНТЕГ, 2001. - 380 с.
3.	Липаев, В.В. Программная инженерия. Методологические основы/ В.В. Липаев. - М.: ТЕИС, 2006.
4.	Львовский, С.М. Набор и верстка в системе ЕТ^Х/С.М. Львовский. - М.: 2003. - 448 с.
5.	Новичков, А. Система генерации проектной документации Rational SoDA/A. Новичков - Компьютер-Пресс #10, 2001.
6.	Walsh, N.. DocBook; The Definitive Guide/Norman Walsh, Leonard Muellner. - O’Reilly Associates, Inc., 1999 - 644 c.
Инте рнет-источники
7.	Бьюри	C.	Adobe	FrameMaker	/
http: / / www.publish.ru/articles/4394767/ text/4041312.html
8.	Васютович В., Самотохин С. Стандартизация в области документирования программных средств. // http://www.osp.ru/cio/1999/12/171500/.
9.	Волков О. Arbortext: система разработки, генерации и публикации технической документации. / http://www.philosoft.ru/arbor.zhtml. -2009.
10.	Карпов В.Э. Об оформлении программной документации. / http: / / www.raai.org/about /persons/karpov/pages/ofdoc/ofdoc.html.
261
262
ЛИТЕРАТУРА
11.	Кондорская М. Технический писатель в большом мире:	специальность и профессия. //
http: //community.livejoumal.com/ru_ techwriters/7983.html
12.	Кознов Д.В.	Введение в программную инженерию.	Лекция	6. Конфигурационное управление /
http: //www.intuit.ru/department/se/inprogeng/6/
13.	Кулямин В.В. Методы верификации программного обеспечения. / http://www.ict.edu.ru/ft/005645/62322el-st09.pdf
14.	Лапыгин Д., Новичков А. Конфигурационное управление проектами разработки программного обеспечения / http://citforum.ru/SE/quality/configuration_management/ #_Тос87205221
15.	Образовательный сайт Чухаревой О.В. CASE-средства. -http: //www.chyhareva.ru/case_sr/index.html.
16.	Острогорский М. Документирование ИТ-Структуры организации, 2007// http://www.philosoft.ru/itdocs.zhtml.
17.	Острогорский М. Кто такие технические писатели, 2006// http: / / www.philosoft.ru/tehpis.zhtml.
18.	Острогорский М. Разработка технической документации с помощью DocBook/XML. Принцип единого источника. // http://www.philosoft.ru/docbook-basics.zhtml. - 2007.
19.	Острогорский М., Потапова Е. Microsoft Word для технического писателя. // http://www.philosoft.ru/wordtips.zhtml. - 2004.
20.	Шапошникова И. MadCap Flare: система для разработки технической документации наГоснове единого источника. Основные возможности и преимущества. / http://www.philosoft,ru/madcapflare.zhtml. - 2008.
21.	Все о DT£X- http://ru.wikipedia.org/wiki/LaTeX
22.	Каким должно быть руководство пользователя // http: //www.philosoft.ru/mgsmall.zhtml.
ЛИТЕРАТУРА
263
23.	Официальный сайт разработчиков программного комплекса Arbortext / http://www.ptc.com.
24.	Официальный сайт разработчиков DocBook/ http://docbook.org/
25.	Программные продукты / http://www.philosoft.ru/software.zhtml.
26.	Проект ГОСТа на стиль изложения. // http: / / www.philosoft .ru/goststyle.zht ml.
27.	Профессиональные технологии бизнеса / http://www.pro-technologies.ru/product/Arbortext/
28.	Русский сайт DocBook http://docbook.ru/about/mdex.html
29.	Технический писатель. Базовые компетенции специалиста// http: //www.philosoft.ru/ twskills.zhtml.
30.	Техническое задание на проектирование / http://www.dom-intel.ru / magazin / uslugi/massadj / tehnicheskoe-zadanie-na-proektirovanie.html
31.	Техническое задание согласно ГОСТу / http://it-gost.ru/content/view/101/51/
32.	IBM Rational Jazz - открытая и расширяемая платформа для разработки программного обеспечения http: //www.ibm.com/developerworks/ru/library/r-jazz/index.html
33.	IBM Rational Rhapsody/ http://www.interface.ru/home.asp?artld=25252
34.	http://www.ctan.org/
35.	http://www.madcapsoftware.com/products/flare/uses.aspx
36.	http://www.miktex.org
37.	http://ru.wikipedia.org/wiki/Beamer_ %28LaTeX%29
38.	http://www.texniccenter.org
39.	http://www.winedt.com
264
ЛИТЕРАТУРА
Стандарты
40.	ГОСТ 34.003-90. Информационная технология. Комплекс стандартов на автоматизированные системы. Термины и определения.
41.	ГОСТ 2.601-95. Единая система конструкторской документации. Эксплуатационные документы.
42.	Международный стандарт IEEE 829	/
http://gerrardconsulting.com/tkb/guidelines/ieee829/main.html (на английском языке).
43.	ISO/IEC 15288. System Engineering -^System Life Cycle Processes. - 2001.
44.	http://store.adobe.ru/catalog/program.php?ID=l15070