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

 

СОДЕРЖАНИЕ

 

 

Введение 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. Переплет

Нумерация.

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