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

Ниже приведена общая  структура документа “Внешняя спецификация”:

1. Описание программного  изделия

2. Цели

3. Стратегия

4. Используемые материалы  (в т.ч. справочные)

5. Передача заказчику  и ввод в действие

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

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

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

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

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

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

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

1. Внешнее описание;
2. Описание архитектуры программы, включая внешнюю спецификацию;
3. Описание модульной системы, включая внешнюю спецификацию каждого включенного модуля;
4. Для каждого модуля - его спецификация и описание его строения;
5. Тексты модулей на выбранном языке программирования;

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

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

 

 

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

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

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

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

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

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

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

3.1 Категории пользователей. 
 Следует различать две категории пользователей: ординарных пользователей программы и администраторов. Ординарный пользователь программы (end-user) использует программу для решения своих задач (в своей предметной области). Это может быть инженер, проектирующий техническое устройство, или кассир, продающий железнодорожные билеты с помощью данной программы. Он может и не знать многих деталей работы компьютера или принципов программирования. Администратор программны (system administrator) управляет использованием программы ординарными пользователями и осуществляет сопровождение программного средства, не связанное с модификацией программ. Например, он может регулировать права доступа к программе между ординарными пользователями, поддерживать связь с поставщиками программы или выполнять определенные действия, чтобы поддерживать программу в рабочем состоянии, если оно включено как часть в другую систему.  
 Состав пользовательской документации зависит от аудиторий пользователей, на которые оно ориентировано, и от режима использования документов. Под аудиторией здесь понимается контингент пользователей, у которого есть необходимость в определенной пользовательской документации. Удачный пользовательский документ существенно зависит от точного определения аудитории, для которой он предназначен. Пользовательская документация должна содержать информацию, необходимую для каждой аудитории. Под режимом использования документа понимается способ, определяющий, каким образом используется этот документ. Обычно пользователю достаточно больших программных систем требуются либо документы для изучения программного средства (использование в виде инструкции), либо для уточнения некоторой информации (использование в виде справочника). 

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

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

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

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

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

 

Заключение

 

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

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

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

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

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

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

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

 

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

 

1. В.Э. Карпов «Об оформлении программной документации» 
2. Путилов В.А. Фильчаков В.В. «Стандартизация процессов обеспечения качества программного обеспечения»
3. Ю.В. Кагарлицкий «Техническая коммуникация: к постановке проблемы»
4. М. Острогорский «Зачем нужны ГОСТ 19 и ГОСТ 34»
5. М. Острогорский «Как мир устроен? Концепционный раздел руководства пользователя»
6. Ю.В. Кагарлицкий «Руководство для разработчиков технической документации к программному обеспечению»
7. О.К Лимашев «Разработка и документация программных средств»
8. Липаев В.В., Филинов Е.Н. «Мобильность программ и данных в открытых информационных системах»
9. Смагин В.А., Солдатенко В.С., Кузнецов В.В. «Моделирование и обеспечение надёжности программных средств»
10. И.В Красльников «Использование ГОСТов и иных стандартов»

 

 

 

 

 

 

 

 

 

 

 

 

Приложения

 

 

 

 

 

 

 

Перечень  документов ЕСПД

 

ГОСТ 19.001-77 ЕСПД	Общие положения.
ГОСТ 19.101-77 ЕСПД	Виды программ и программных  документов
ГОСТ 19.102-77 ЕСПД	Стадии разработки.
ГОСТ 19.103-77 ЕСПД	Обозначение программ и программных  документов.
ГОСТ 19.104-78 ЕСПД	Основные надписи.
ГОСТ 19.105-78 ЕСПД	Общие требования к программным  документам.
ГОСТ 19.106-78 ЕСПД	Требования к программным  документам, выполненным печатным способом.
ГОСТ 19.201-78 ЕСПД	Техническое задание. Требования к содержанию и оформлению.
ГОСТ 19.202-78 ЕСПД	Спецификация. Требования к  содержанию и оформлению.
ГОСТ 19.301-79 ЕСПД	Порядок и методика испытаний.
ГОСТ 19.401-78 ЕСПД	Текст программы. Требования к содержанию и оформлению.
ГОСТ 19.402-78 ЕСПД	Описание программы.
ГОСТ 19.404-79 ЕСПД	Пояснительная записка. Требования к содержанию и оформлению.
ГОСТ 19.501-78 ЕСПД	Формуляр. Требования к содержанию и оформлению.
ГОСТ 19.502-78 ЕСПД	Описание применения. Требования к содержанию и оформлению.
ГОСТ 19.503-79 ЕСПД	Руководство системного программиста. Требования к содержанию и оформлению.
ГОСТ 19.504-79 ЕСПД	Руководство программиста.
ГОСТ 19.505-79 ЕСПД	Руководство оператора.
ГОСТ 19.506-79 ЕСПД	Описание языка.
ГОСТ 19.508-79 ЕСПД	Руководство по техническому обслуживанию. Требования к содержанию и оформлению.
ГОСТ 19.604-78 ЕСПД	Правила внесения изменений  в программные документы, выполняемые  печатным способом.
ГОСТ 19.701-90 ЕСПД	Схемы алгоритмов, программ, данных и систем. Условные обозначения  и правила выполнения.
ГОСТ 19.781-90	Обеспечение систем обработки  информации программное