литературА ………….. .................................................................................................. 28
Приложение А.ЛИСТИНГ ПРОГРАММЫ (фрагмент)............................................. 29
Руководство оператора
Составление документации для пользователей имеет свои особенности, связанные с тем, что пользователь, как правило, не является профессионалом в области разработки программного обеспечения. В книге С. Дж. Гримм даны рекомендации по написанию подобной программной документации:
• учитывайте интересы пользователей - руководство должно содержать все инструкции, необходимые пользователю;
• избегайте технического жаргона и узко специальной терминологии, если все же необходимо использовать некоторые термины, то их следует пояснить;
• будьте точны и рациональны - длинные и запутанные руководства обычно никто не читает, например, лучше привести рисунок формы, чем долго ее описывать.
Руководство пользователя, как правило, содержит следующие разделы:
• общие сведения о программном продукте;
• описание установки;
• описание запуска;
• инструкции по работе (или описание пользовательского интерфейса);
• сообщения пользователю.
Раздел «Общие сведения о программе» обычно содержит наименование программного продукта, краткое описание его функций, реализованных методов и возможных областей применения.
Раздел Установка обычно содержит подробное описание действий по установке программного продукта и сообщений, которые при этом могут быть получены.
В разделе Запуск, как правило, описаны действия по запуску программного продукта и сообщений, которые при этом могут быть получены.
Раздел Инструкции по работе обычно содержит описание режимов работы, форматов ввода-вывода информации и возможных настроек.
Раздел Сообщения пользователю должен содержать перечень возможных сообщений, описание их содержания и действий, которые необходимо предпринять по этим сообщениям.
Руководство системного программиста
По ГОСТ 19.503-79 руководство системного программиста должно содержать всю информацию, необходимую для установки программного обеспечения, его настройки и проверки работоспособности. Кроме того, как указывалось выше, в него часто включают и описание необходимого обслуживания, которое раньше приводилось в руководстве оператора (ГОСТ 19.505-79) и/или руководстве по техническому обслуживанию (ГОСТ 19.508-79). В настоящее время данную схему используют для составления руководства системному администратору.
Руководство системного программиста должно содержать следующие разделы:
• общие сведения о программном продукте,
• структура,
• настройка,
• проверка,
• дополнительные возможности,
• сообщения системному программисту.
Раздел Общие сведения о программе должен включать описание назначения и функций программы, а также сведения о технических и программных средствах, обеспечивающих выполнение данной программы (например, объем оперативной памяти, требования к составу и параметрам внешних устройств, требования к программному обеспечению и т. п.).
В разделе Структура программы должны быть приведены сведения о структуре программы, ее составных частях, о связях между составными частями и о связях с другими программами.
В разделе Настройка программы должно быть приведено описание действий по настройке программы на условия практического применения.
В разделе Проверка программы должно быть приведено описание способов проверки работоспособности программы, например контрольные примеры.
В разделе Дополнительные возможности должно быть приведено описание дополнительных возможностей программы и способов доступа к ним.
В разделе Сообщения системному программисту должны быть указаны тексты сообщений, выдаваемых в ходе выполнения настройки и проверки программы, а также в ходе ее выполнения, описание их содержания и действий, которые необходимо предпринять по этим сообщениям.
Основные правила оформления программной документации
При оформлении текстовых и графических материалов, входящих в программную документацию следует придерживаться действующих стандартов. Некоторые положения этих стандартов приведены ниже.
Оформление текстового и графического материала. Текстовые документы оформляют на листах формата А4, причем графический материал допускается представлять на листах формата A3. Поля на листе определяют в соответствии с общими требованиями: левое - не менее 30, правое - не менее 10, верхнее - не менее 15, а нижнее - не менее 20 мм. В текстовых редакторах для оформления записки параметры страницы заказывают в зависимости от устройства печати. При ручном оформлении документов параметры страницы выбирают из соображений удобства.
Нумерация всех страниц - сквозная. Номер проставляется сверху справа арабской цифрой. Страницами считают, как листы с текстами и рисунками, так и листы приложений. Первой страницей считается титульный лист. Номер страницы на титульном листе не проставляют.
Наименование разделов пишут прописными буквами в середине строки. Расстояние между заголовками и текстом, а также между заголовками раздела и подразделов должно быть равно:
• при выполнении документа машинописным способом - двум интервалам;
• при выполнении рукописным способом - 10 мм;
• при использовании текстовых редакторов - определяется возможностями редактора.
Наименования подразделов и пунктов следует размещать с абзацного отступа и печатать вразрядку с прописной буквы, не подчеркивая и без точки в конце. Расстояние между последней строкой текста предыдущего раздела и последующим заголовком при расположении их на одной странице должно быть равно:
• при выполнении документа машинописным способом - трем интервалам;
• при выполнении рукописным способом - не менее 15 мм;
• при использовании текстовых редакторов - определяется возможностями редактора.
Разделы и подразделы нумеруются арабскими цифрами с точкой. Разделы должны иметь порядковые номера 1, 2, и т. д. Номер подраздела включает номер раздела и порядковый номер подраздела, входящего в данный раздел, разделенные точкой. Например: 2.1, 3.5. Ссылки на пункты, разделы и подразделы указывают, используя порядковый номер раздела или пункта, например, «в разд. 4», «в п. 3.3.4».
Разработка технического задания
Техническое задание представляет собой документ, в котором сформулированы основные цели разработки, требования к программному продукту, определены сроки и этапы разработки и регламентирован процесс приемно-сдаточных испытаний. В разработке технического задания участвуют как представители заказчика, так и представители исполнителя. В основе этого документа лежат исходные требования заказчика, анализ передовых достижений техники, результаты выполнения научно-исследовательских работ, предпроектных исследований, научного прогнозирования и т. п.
Разработка технического задания выполняется в следующей последовательности. Прежде всего, устанавливают набор выполняемых функций, а также перечень и характеристики исходных данных. Затем определяют перечень результатов, их характеристики и способы представления. Далее уточняют среду функционирования программного обеспечения: конкретную комплектацию и параметры технических средств, версию используемой операционной системы и, возможно, версии и параметры другого установленного программного обеспечения, с которым предстоит взаимодействовать будущему программному продукту.
В случаях, когда разрабатываемое программное обеспечение собирает и хранит некоторую информацию или включается в управление каким-либо техническим процессом, необходимо также четко регламентировать действия программы в случае сбоев оборудования и энергоснабжения.
На техническое задание существует стандарт ГОСТ 19.201-78 «Техническое задание. Требования к содержанию и оформлению». В соответствии с этим стандартом техническое задание должно содержать следующие разделы:
• введение;
• основания для разработки;
• назначение разработки;
• требования к программе или программному изделию;
• требования к программной документации;
• технико-экономические показатели;
• стадии и этапы разработки;
• порядок контроля и приемки.
При необходимости допускается в техническое задание включать приложжения. Рассмотрим более подробно содержание каждого раздела.
Введение должно включать наименование и краткую характеристику области применения программы или программного продукта, а также объекта (например, системы) в котором предполагается их использовать. Основное назначение введения - продемонстрировать актуальность данной разработки и показать, какое место эта разработка занимает в ряду подобных.
Раздел Основания для разработки должен содержать наименование документа, на основании которого ведется разработка, организации, утвердившей данный документ, и наименование или условное обозначение темы разработки. Таким документом может служить план, приказ, договор и т. п.
Раздел Назначение разработки должен содержать описание функционального и эксплуатационного назначения программного продукта с указанием категорий пользователей.
Раздел Требования к программе или программному изделию должен включать следующие подразделы:
• требования к функциональным характеристикам;
• требования к надежности;
• условия эксплуатации;
• требования к составу и параметрам технических средств;
• требования к информационной и программной совместимости;
• требования к маркировке и упаковке;
• требования к транспортированию и хранению;
• специальные требования.
Наиболее важным из перечисленных выше является подраздел Требования к функциональным характеристикам. В этом разделе должны быть перечислены выполняемые функции и описаны состав, характеристики и формы представления исходных данных и результатов. В этом же разделе при необходимости указывают критерии эффективности: максимально допустимое время ответа системы, максимальный объем используемой оперативной и/или внешней памяти и др.
Примечание. Если разработанное программное обеспечение не будет выполнять указанных в техническом задании функций, то оно считается не соответствующим техническому заданию. Универсальность будущего продукта также обычно специально не оговаривается, но подразумевается.
В подразделе Требования к надежности указывают уровень надежности, который должен быть обеспечен разрабатываемой системой и время восстановления системы после сбоя. Для систем с обычными требованиями к надежности в этом разделе иногда регламентируют действия разрабатываемого продукта по увеличению надежности результатов (контроль входной и выходной информации, создание резервных копий промежуточных результатов и т. п.).
В подразделе Условия эксплуатации, указывают особые требования к условиям эксплуатации: температуре окружающей среды, относительной влажности воздуха и т. п. Как правило, подобные требования формулируют,
если разрабатываемая система будет эксплуатироваться в нестандартных условиях или использует специальные внешние устройства, например для хранения информации. Здесь же указывают вид обслуживания, необходимое количество и квалификация персонала. В противном случае допускается указывать, что требования не предъявляются.
В подразделе Требования к составу и параметрам технических средств указывают необходимый состав технических средств с указанием их основных технических характеристик: тип микропроцессора, объем памяти, наличие внешних устройств и т. п. При этом часто указывают два варианта конфигурации: минимальный и рекомендуемый.
В подразделе Требования к информационной и программной совместимости при необходимости можно задать методы решения, определить язык или среду программирования для разработки, а также используемую операционную систему и другие системные и пользовательские программные средства, с которым должно взаимодействовать разрабатываемое программное обеспечение. В этом же разделе при необходимости указывают, какую степень защиты информации необходимо предусмотреть.
В разделе Требования к программной документации указывают необходимость наличия руководства программиста, руководства пользователя, руководства системного программиста, пояснительной записки и т. п. На все эти типы документов также существуют ГОСТы.
В разделе Технико-экономические показатели рекомендуется указывать ориентировочную экономическую эффективность, предполагаемую годовую потребность и экономические преимущества по сравнению с существующими аналогами.
В разделе Стадии и этапы разработки указывают стадии разработки, этапы и содержание работ с указанием сроков разработки и исполнителей.
В разделе Порядок контроля и приемки указывают виды испытаний и общие требования к приемке работы.
В приложениях при необходимости приводят: перечень научно-исследовательских работ, обосновывающих разработку; схемы алгоритмов, таблицы, описания, обоснования, расчеты и другие документы, которые следует использовать при разработке.
В зависимости от особенностей разрабатываемого продукта разрешается уточнять содержание разделов, т. е. использовать подразделы, вводить новые разделы или объединять их.
В случаях, если какие-либо требования, предусмотренные техническим заданием, заказчик не предъявляет, следует в соответствующем месте указать «Требования не предъявляются». Разработка технического задания - процесс трудоемкий, требующий определенных навыков. Наиболее сложным, как правило, является четкое формулирование основных разделов: введения, назначения и требований к программному продукту. В качестве примера рассмотрим техническое задания на выполнение курсового проектирования госбюджетной научно-исследовательской работы.
МИНИСТЕРСТВО ОБРАЗОВАНИЯ И НАУКИ рОССИЙСКОЙ ФЕДЕРАЦИИ
(МИНОБРНАУКИ РОССИИ)
Федеральное государственное бюджетное образовательное учреждение высшего профессионального образования
«Санкт-Петербургский государственный политехнический университет» (ФГБОУ ВПО «СПбГПУ»)
