Виды программных документов. Пояснительная записка. Руководство пользователя. Руководство системного программиста. Основные правила оформления программной документации.

Урок 28.

Предмет: Технология разработки программных продуктов.

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

Цели:

Образовательная

Ознакомление с видами  документов при разработки ПО.

Развивающая:

Развивать умение слушать других, делать выводы и обобщать полученные знания

Воспитательная:

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

Межпредметные связи:

-         Английский язык

-         Операционные системы

-         Информационные технологии

-         Основы алгоритмизации и программирования

Оборудование: доска, мел, письменные принадлежности, проектор, ПК

Тип урока: комбинированный

Метод обучения: Объяснительно иллюстративный

Ход урока:

1.Организационный момент

         - Проверка готовности кабинета

         - Объявление темы

2. Постановка цели урока

3.Повторение пройденного материала

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

     Инструментальные системы технологии программирования

     Инструментальные средства разработки программ

 

4.Сообщение новых знаний

1.      Виды программных документов

2.      Пояснительная записка

3.      Руководство пользователя

4.      Руководство системного программиста

5.      Основные правила оформления программной документации

 

5. Восприятие и осознание учащимися нового материала

6. Осмысление обобщение и систематизация знаний

7. Подведение итогов урока и  постановка домашнего задания

   Выучить содержимое темы

Гагарина Л.Г.  стр. С.233-238.

        Ответить на вопросы:

 

 

 

Лекция №11:Составление программной документации

 

Учебные вопросы:

6.      Виды программных документов

7.      Пояснительная записка

8.      Руководство пользователя

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

10.  Основные правила оформления программной документации

11.  Правила оформления расчетно-пояснительных записок при курсовом проектировании

 

 

 

ВВЕДЕНИЕ

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

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

 

 

1. Виды программных документов

 

 

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

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

Ведомость держателей подлинников (код вида документа - 05) должна содержать список предприятий, на которых хранятся подлинники программ­ных документов. Необходимость этого документа определяется на этапе раз­работки и утверждения технического задания только для программного обес­печения со сложной архитектурой.

Текст программы (код вида документа - 12) должен содержать текст программы с необходимыми комментариями. Необходимость этого докумен­та определяется на этапе разработки и утверждения технического задания.

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

Ведомость эксплуатационных документов (код вида документа - 20) должна содержать перечень эксплуатационных документов на программу, к которым относятся документы с кодами: 30, 31, 32, 33, 34, 35, 46. Необходи­мость этого документа также определяется на этапе разработки и утвержде­ния технического задания.

Формуляр (код вида документа - 30) должен содержать основные харак­теристики программного обеспечения, комплектность и сведения об эксплу­атации программы.

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

Руководство системного программиста (код вида документа - 32) должно содержать сведения для проверки, обеспечения функционирования и настройки программы на условия конкретного применения.

Руководство программиста (код вида документа - 33) должно содер­жать сведения для эксплуатации программного обеспечения.

Руководство оператора (код вида документа - 34) должно содержать сведения для обеспечения процедуры общения оператора с вычислительной системой в процессе выполнения программного обеспечения.

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

Руководство по техническому обслуживанию (код вида документа - 46) должно содержать сведения для применения тестовых и диагностических программ при обслуживании технических средств.

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

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

Прочие документы (коды вида документа - 90-99) могут составляться на любых стадиях разработки, т. е. на стадиях эскизного, технического и ра­бочего проектов.

Допускается объединять отдельные виды эксплуатационных докумен­тов, кроме формуляра и ведомости. Необходимость объединения указывает­ся в техническом задании, а имя берут у одного из объединяемых документов. Например, в настоящее время часто используется эксплуатационный до­кумент, в который отчасти входит руководство системного программиста, программиста и оператора. Он называется «Руководство пользователя» (см §3).

Рассмотрим наиболее важные программные документы более подробно.

 

2. Пояснительная записка

 

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

Содержание пояснительной записки по стандарту (ГОСТ 19.404-79) должно выглядеть следующим образом:

• введение;

  назначение и область применения;

• технические характеристики;

• ожидаемые технико-экономические показатели;

• источники, используемые при разработке.

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

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

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

• постановка задачи, описание применяемых математических методов и допущений и ограничений, связанных с выбранным математическим аппара­том;

  описание алгоритмов и функционирования программы с обосновани­ем принятых решений;

  описание и обоснование выбора способа организации входных и вы­ходных данных;

• описание и обоснование выбора состава технических и программных средств на основании проведенных расчетов или анализов.

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

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

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

 

3. Руководство пользователя

 

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

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

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

• излагайте ясно, используйте короткие предложения;

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

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

Руководство пользователя, как правило, содержит следующие разделы:

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

• описание установки;

• описание запуска;

• инструкции по работе (или описание пользовательского интерфейса);

• сообщения пользователю.

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

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

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

Раздел Инструкции по работе обычно содержит описание режимов ра­боты, форматов ввода-вывода информации и возможных настроек.

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

 

4. Руководство системного программиста

 

По ГОСТ 19.503-79 руководство системного программиста должно со­держать всю информацию, необходимую для установки программного обес­печения, его настройки и проверки работоспособности. Кроме того, как ука­зывалось выше, в него часто включают и описание необходимого обслужи­вания, которое раньше приводилось в руководстве оператора (ГОСТ 19.505-79) и/или руководстве по техническому обслуживанию (ГОСТ 19.508-79). В настоящее время данную схему используют для составления руководства системному администратору.

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

• общие сведения о программном продукте,

• структура,

• настройка,

• проверка,

• дополнительные возможности,

• сообщения системному программисту.

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

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

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

В разделе Проверка программы должно быть приведено описание спо­собов проверки работоспособности программы, например контрольные при­меры.

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

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

 

5. Основные правила оформления программной документации

 

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

Оформление текстового и графического материала. Текстовые доку­менты оформляют на листах формата А4, причем графический материал до­пускается представлять на листах формата A3. Поля на листе определяют в соответствии с общими требованиями: левое - не менее 30, правое - не ме­нее 10, верхнее - не менее 15, а нижнее - не менее 20 мм. В текстовых редак­торах для оформления записки параметры страницы заказывают в зависимо­сти от устройства печати. При ручном оформлении документов параметры страницы выбирают из соображений удобства.

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

Наименование разделов пишут прописными буквами в середине строки. Расстояние между заголовками и текстом, а также между заголовками разде­ла и подразделов должно быть равно:

• при выполнении документа машинописным способом - двум интерва­лам;

• при выполнении рукописным способом - 10 мм;

  при использовании текстовых редакторов - определяется возможнос­тями редактора.

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

• при выполнении документа машинописным способом - трем интерва­лам;

• при выполнении рукописным способом - не менее 15 мм;

  при использовании текстовых редакторов - определяется возможнос­тями редактора.

Разделы и подразделы нумеруются арабскими цифрами с точкой. Разде­лы должны иметь порядковые номера 1, 2, и т. д. Номер подраздела включа­ет номер раздела и порядковый номер подраздела, входящего в данный раз­дел, разделенные точкой. Например: 2.1, 3.5. Ссылки на пункты, разделы и подразделы указывают, используя порядковый номер раздела или пункта, на­пример, «в разд. 4», «в п. 3.3.4».

Текст разделов печатают через 1,5-2 интервала. При использовании тек­стовых редакторов высота букв и цифр должна быть не менее 1,8 мм (шриф­ты № 11-12).

Перечисления следует нумеровать арабскими цифрами со скобкой, на­пример: 2), 3) и т. д. - с абзацного отступа. Допускается выделять перечисле­ние простановкой дефиса перед пунктом текста или символом, его заменяю­щим, в текстовых редакторах.

Оформление рисунков, схем алгоритмов, таблиц и формул. В соответст­вии с ГОСТ 2.105-79 «Общие требования к текстовым документам» иллюс­трации (графики, схемы, диаграммы) могут быть приведены как в основном тексте, так и в приложении. Все иллюстрации именуют рисунками. Все ри­сунки, таблицы и формулы нумеруют арабскими цифрами последовательно (сквозная нумерация) или в пределах раздела (относительная нумерация). В приложении - в пределах приложения.

Каждый рисунок должен иметь подрисуночную подпись - название, по­мещаемую под рисунком, например:

Рис.12. Форма окна основного меню

На все рисунки, таблицы и формулы в записке должны быть ссылки в виде: «(рис. 12)» или «форма окна основного меню приведена на рис. 12».

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

Если рисунок занимает более одной страницы, на всех страницах, кроме первой, проставляется номер рисунка и слово «Продолжение». Например:

Рис. 12. Продолжение

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

Схемы алгоритмов должны быть выполнены в соответствии со стандар­том ЕСПД. Толщина сплошной линии при вычерчивании схем алгоритмов должна составлять от 0,6... 1,5 мм. Надписи на схемах должны быть выполне­ны чертежным шрифтом, высота букв и цифр должна быть не менее 3,5 мм.

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

Ссылки на таблицы в тексте пояснительной записки указывают в виде слова «табл.» и номера таблицы. Например:

Результаты тестов приведены в табл. 4.

Номер формулы ставится с правой стороны страницы в круглых скобках на уровне формулы. Например:

z:=sin(x)+ln(y);                                          (12)

Ссылка на номер формулы дается в скобках. Например: «расчет значе­ний проводится по формуле (12)».

Оформление приложений. Каждое приложение должно начинаться с новой страницы с указанием в правом углу слова «ПРИЛОЖЕНИЕ» пропис­ными буквами и иметь тематический заголовок. При наличии более одного приложения все они нумеруются арабскими цифрами: ПРИЛОЖЕНИЕ 1, ПРИЛОЖЕНИЕ 2 и т. д. Например:

ПРИЛОЖЕНИЕ 2 Титульный лист расчетно-пояснительной записки

Рисунки и таблицы, помещаемые в приложении, нумеруют арабскими цифрами в пределах каждого приложения с добавлением буквы «П», Напри­мер:

Рис. П. 12 - 12-й рисунок приложения; Рис. П1.2 - 2-й рисунок 1-го приложения.

Если в приложении приводится текст программы, то каждый файл оформляют как рисунок с наименованием файла и его назначением, напри­мер:

Рис. П2.4. Файл menuran.pas - программа движения курсора основного меню.

 

Оформление списка литературы.

Список литературы должен вклю­чать все использованные источники. Сведения о книгах (монографиях, учеб­никах, пособиях, справочниках и т. д.) должны содержать: фамилию и ини­циалы автора, заглавие книги, место издания, издательство, год издания. При наличии трех и более авторов допускается указывать фамилию и инициалы только первого из них со словами «и др.». Издательство надо приводить пол­ностью в именительном падеже: допускается сокращение названия только двух городов: Москва (М.) и Санкт-Петербург (СПб.).

Сведения о статье из периодического издания должны включать: фами­лию и инициалы автора, наименование статьи, издания (журнала), серии (ее-

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

При ссылке на источник из списка литературы (особенно при обзоре аналогов) надо указывать порядковый номер по списку литературы, заклю­ченный в квадратные скобки; например: [5].

 

 

 

 

 

Лекция 13. ДОКУМЕНТИРОВАНИЕ ПРОГРАММНЫХ СРЕДСТВ

 

13.1. Документация, создаваемая в процессе разработки программных средств.

 

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

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

Документы управления разработкой ПС.

Документы, входящие в состав ПС.

Документы управления разработкой ПС (process documentation), протоколируют процессы разработки и сопровождения ПС, обеспечивая связи внутри коллектива разработчиков и между коллективом разработчиков и менеджерами (managers) - лицами, управляющими разработкой. Эти документы могут быть следующих типов [13.1]:

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

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

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

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

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

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

Пользовательская документация ПС (П-документация).

Документация по сопровождению ПС (С-документация).

 

13.2. Пользовательская документация программных средств.

 

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

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

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

В соответствии с работами [13.1, 13.2] можно считать типичным следующий состав пользовательской документации для достаточно больших ПС:

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

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

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

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

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

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

 

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

 

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

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

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

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

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

Внешнее описание ПС (Requirements document).

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

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

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

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

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

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

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

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

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

Литература к лекции 13.

 

13.1. Ian Sommerville. Software Engineering. - Addison-Wesley Publishing Company, 1992. P.

13.2. ANSI/IEEE Std 1063-1988, IEEE Standard for Software User Documentation.

13.3. ANSI/IEEE Std 830-1984, IEEE Guide for Software Requirements Specification.

13.4. ANSI/IEEE Std 1016-1987, IEEE Recommended Practice for Software Design Description.

13.5. ANSI/IEEE Std 1008-1987, IEEE Standard for Software Unit Testing.

13.6. ANSI/IEEE Std 1012-1986, IEEE Standard for Software Verification and Validation Plans.

13.7. ANSI/IEEE Std 983-1986, IEEE Guide for Software Quality Assurance Planning.

13.8. ANSI/IEEE Std 829-1983, IEEE Standard for Software Test Documentation.

 

ющие под­разделы:

• постановка задачи, описание применяемых математических методов и допущений и ограничений, связанных с выбранным математическим аппара­том;

  описание алгоритмов и функционирования программы с обосновани­ем принятых решений;

  описание и обоснование выбора способа организации входных и вы­ходных данных;

• описание и обоснование выбора состава технических и программных средств на основании проведенных расчетов или анализов.

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

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

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

 

3. Руководство пользователя

 

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

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

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

• излагайте ясно, используйте короткие предложения;

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

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

Руководство пользователя, как правило, содержит следующие разделы:

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

• описание установки;

• описание запуска;

• инструкции по работе (или описание пользовательского интерфейса);

• сообщения пользователю.

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

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

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

Раздел Инструкции по работе обычно содержит описание режимов ра­боты, форматов ввода-вывода информации и возможных настроек.

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

 

4. Руководство системного программиста

 

По ГОСТ 19.503-79 руководство системного программиста должно со­держать всю информацию, необходимую для установки программного обес­печения, его настройки и проверки работоспособности. Кроме того, как ука­зывалось выше, в него часто включают и описание необходимого обслужи­вания, которое раньше приводилось в руководстве оператора (ГОСТ 19.505-79) и/или руководстве по техническому обслуживанию (ГОСТ 19.508-79). В настоящее время данную схему используют для составления руководства системному администратору.

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

• общие сведения о программном продукте,

• структура,

• настройка,

• проверка,

• дополнительные возможности,