Документирование программных средств

 

СОДЕРЖАНИЕ

 

 

Введение 3

ГЛАВА 1. Стандарты оформления документации 4

1.1 Процесс документирования. 6

1.2 План документирования. 7

1.3 Содержание спецификации стиля 9

ГЛАВА 2. Проектная документация 11

2.1 Техническое задание 14

2.2 Внутренние и внешние языки спецификации 16

2.3 Документация по сопровождению программы 17

Глава 3.Пользовательская документация. 19

3.1 Категории пользователей 20

3.2 Состав пользовательской документации 21

Заключение 23

Список литературы 25

Приложения 26

 

 

 

 

Введение

 

Когда программист-разработчик  получает в той или иной форме  задание на программирование, перед  ним, перед руководителем проекта  и перед всей проектной группой  встают вопросы:

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

Кроме упомянутых вопросов есть и другие.

На эти и массу других вопросов когда-то отвечали государственные  стандарты на программную документацию комплекс стандартов 19-й серии ГОСТ ЕСПД. Но уже тогда у программистов  была масса претензий к этим стандартам. Что-то требовалось дублировать  в документации много раз (как, казалось - неоправданно), а многое не было предусмотрено, как, например, отражение специфики  документирования программ, работающих с интегрированной базой данных.

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

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

Эту документацию можно разбить  на две группы:

• Документы управления разработкой ПС.
• Документы, входящие в состав ПС.

 

 

ГЛАВА 1. Стандарты оформления документации

 

Основу отечественной  нормативной базы в области документирования ПС составляет комплекс стандартов Единой системы программной документации (ЕСПД). Основная и большая часть  комплекса ЕСПД была разработана  в 70-е и 80-е годы. Сейчас этот комплекс представляет собой систему межгосударственных стандартов стран СНГ (ГОСТ), действующих  на территории Российской Федерации на основе межгосударственного соглашения по стандартизации.

Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС, и связаны, по большей  части, с документированием функциональных характеристик ПС. Следует отметить, что стандарты ЕСПД (ГОСТ 19.xxx-xx) носят рекомендательный характер. Впрочем, это относится и ко всем другим стандартам в области ПС (ГОСТ 34.xxx-xx, Международному стандарту ISO/IEC, и др.). Дело в том, что в соответствии с Законом РФ "О стандартизации" эти стандарты становятся обязательными на контрактной основе - то есть при ссылке на них в договоре на разработку (поставку) ПС.

Говоря о состоянии  ЕСПД в целом, можно констатировать, что большая часть стандартов ЕСПД морально устарела.

К числу основных недостатков  ЕСПД можно отнести:

• ориентацию на единственную, "каскадную" модель жизненного цикла (ЖЦ) ПС;
• отсутствие четких рекомендаций по документированию характеристик качества ПС;
• отсутствие системной увязки с другими действующими отечественными системами стандартов по ЖЦ и документированию продукции в целом, например, ЕСКД;
• нечетко выраженный подход к документированию ПС как товарной продукции;
• отсутствие рекомендаций по самодокументированию ПС, например, в виде экранных меню и средств оперативной помощи пользователю ("хелпов");
• отсутствие рекомендаций по составу, содержанию и оформлению перспективных документов на ПС, согласованных с рекомендациями международных и региональных стандартов.

Итак, ЕСПД нуждается в  полном пересмотре на основе стандарта  ИСО/МЭК 12207-95 на процессы жизненного цикла  ПС об этом стандарте далее будет  сказано подробнее).

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

Международный стандарт ISO/IEC 12207: 1995-08-01 на организацию ЖЦ продуктов  программного обеспечения (ПО) - казалось бы весьма неконкретный, но вполне новый  и отчасти "модный" стандарт.

Стандарты комплекса ГОСТ 34.xxx-xx на создание и развитие автоматизированных систем (АС) - обобщенные, но воспринимаемые как весьма жесткие по структуре ЖЦ и проектной документации. Но эти стандарты многими считаются бюрократическими до вредности и консервативными до устарелости.

Прошло много лет, программирование происходит в среде совершенно новых  технологий, многие программисты, работая  в стиле drag-and-drop, могут годами не видеть текст своих программ. Это не значит, что исчезла необходимость в их документировании. Более того, вопросы о наличии хоть какой-то системы, регламентирующей эту сторону создания программных средств, продолжают задавать постоянно. Спрашивают и о том, есть ли обязательные для применения стандарты (особенно остро стоит этот вопрос, когда разработка выполняется по заказу государственной организации или предприятия). Интересуются и тем, где можно купить имеющиеся стандарты.

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

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

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

1.1 Процесс документирования.

Заказчик должен обеспечивать документатору доступ:

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

b) к рабочей копии программного  средства (при необходимости);

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

d) к типичным пользователям  (по возможности) для анализа  аудитории и тестирования на  практичность.

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

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

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

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

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

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

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

План документирования должен охватывать следующие вопросы (но не ограничиваться ими):

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

b) спецификацию стиля;

c) определение аудитории  пользователей;

d) обоснование причин  использования документации данной  аудиторией и ее целевое назначение;

e) содержание (план-проспект) документации, с оценкой ее постраничного  объема, и соответствующие уточнения  для других машинных носителей  документации;

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

g) установление собственника  авторских прав на документацию  и любых других прав собственности.³

h) обеспечение перевода  документации на другие языки.

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

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

k) методы и средства  производства (тиражирования) и используемые  версии данных средств;

l) структуру коллектива  разработчиков документации и,  возможно, плана выбора данной  структуры.⁴

m) взаимосвязи (подчиненности)  проекта;

n) почасовую загрузку  и зарплату персонала;

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

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

q) планы контроля изменений  и сопровождения документации (факультативно);

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

s) календарное планирование (графики) по контрольным точкам (milestones), включая (при необходимости):

1) утверждение плана документирования,

2) подготовку, проверку и  корректировку проекта каждого  документа,

3) тестирование на практичность,

4) подготовку оригиналов  фотошаблонов,

5) распечатку, переплетение  и распространение документации.

1.3 Содержание спецификации стиля

Язык

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

Орфография

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

Грамматика и  ее применение

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

Для бумажной документации:

1. Размер (формат) бумаги
2. Ориентация (расположение)
3. Одно- или двусторонняя печать
4. Разрешающая способность типографского или лазерного способа печати
5. Ширина внутреннего поля
6. Ширина внешних полей
7. Цвета красок
8. Цвет, масса и качество бумаги
9. Разделители
10. Метод воспроизведения (тиражирования) и качество
11. Переплет

Нумерация.

• Нумерация страниц.

Должна быть определена схема  нумерации страниц.

1. Каждая страница должна  иметь индивидуальный номер. Номера  страниц должны быть проставлены  в порядке их брошюрования.

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

3. В случае брошюровки  документа без замены страниц  используют порядковую нумерацию,  например «1», «2» и т.д. Иногда  для нумерации страниц содержания  используют другую схему («i»,  «ii» и т.д.). Следует избегать схожих методов нумерации страниц вспомогательного (указателя и т.д.) и вводного материалов, так как это может привести к неоднозначности в случае изъятия или вставки страниц.

• Нумерация таблиц и рисунков.

Должны быть определены схемы  нумерации рисунков и таблиц (при  необходимости их нумерации).

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

 

 

 

ГЛАВА 2. Проектная документация

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

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

Часто при составлении  технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.

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

Документация по сопровождению  программного средства (system documentation) описывает программное средство с точки зрения ее разработки.

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

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

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

2. документацию, помогающую  вносить изменения в программное  средство.

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

Внешнее описание программного средства (Requirements document).

Описание архитектуры  программного средства (description of the system architecture), включая внешнюю спецификацию каждой ее программы.

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

Для каждого модуля - его  спецификация и описание его строения (design description).

Тексты модулей на выбранном  языке программирования (program source code listings).

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

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

Документация второй группы содержит

Руководство по сопровождению  программного средства (system maintenance guide), которое описывает известные проблемы вместе с программным средством, описывает, какие части системы являются аппаратно- и программно- зависимыми, и как развитие программного средства принято в расчет в его строении (конструкции).

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

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

 

 

2.1 Техническое  задание

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

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

Техническое задание должно содержать следующие разделы:

введение;

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

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

В разделе “Введение” указывается  наименование, краткая характеристика области применения ПО.

 В разделе “Основания  для разработки” указывается:

• документ (документы), на основание которых ведется разработка;
• организация, утвердившая документ, и дата утверждения;
• наименование (условное обозначение) темы разработки.

В разделе Назначение разработки должно быть указано функциональное и эксплуатационное назначение ПО.

 Например, UML – как  универсальный язык моделирования.  Может использоваться и для  постановки технического задания.

Техническое задание позволяет:

- исполнителю — понять  суть задачи, показать заказчику  «технический облик» будущего  изделия, программного изделия  или автоматизированной системы; 

- заказчику — осознать, что именно ему нужно; 

- обеим сторонам —  представить готовый продукт; 

- исполнителю — спланировать  выполнение проекта и работать  по намеченному плану; 

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

- исполнителю — отказаться  от выполнения работ, не указанных  в ТЗ;

- заказчику и исполнителю  — выполнить попунктную проверку готового продукта (приёмочное тестирование — проведение испытаний);

- избежать ошибок, связанных  с изменением требований (на всех  стадиях и этапах создания, за  исключением испытаний).

В зависимости от ожиданий заказчика существует три альтернативы для выбора шаблона Технического задания. Если заказчик требует оформления документации в соответствии с государственным  стандартом, выбор делается в сторону  стандарта ГОСТ 34.602-89. Подготовка Технического задания по ГОСТ 34.602-89 требует значительных временных затрат.

Если поставлены сжатые сроки  подготовки ТЗ и заказчик не требует  оформления документации в соответствии с государственным стандартом, то можно использовать шаблон технического задания по стандарту IEEE Std 830. Стандарт IEEE Std 830 предполагает, что детальные требования могут быть обширными и не существует оптимальной структуры для всех систем. По этой причине, стандартом рекомендуется обеспечивать такое структурирование детальных требований, которое делает их оптимальными для понимания. Стандартом рекомендуются различные способы структурирования детальных требований для различных классов систем.

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

2.2 Внутренние  и внешние языки спецификации

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

• Соглашение о требованиях;
• Внешняя спецификация;
• Внутренняя спецификация.

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