ЛЕКЦИЯ №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 - программа движения курсора основного меню.