Руководство программиста руководство пользователя руководство администратора

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

303

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

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

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

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

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

•структура,

•настройка,

•проверка,

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

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

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

ипараметрам внешних устройств, требования к программному обеспечению и т. п.).

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

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

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

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

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

304

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

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

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

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

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

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

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

•при использовании текстовых редакторов – определяется возможностями редактора. Наименования подразделов и пунктов следует размещать с абзацного отступа и

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

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

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

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

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

305

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

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

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

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

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

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

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

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

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

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

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

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

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

306

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

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

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

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

ПРИЛОЖЕНИЕ 2

Титульный лист расчетно–пояснительной записки

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

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

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

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

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

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

307

Соседние файлы в предмете Программирование

  • #
  • #
  • #
Источник

Привет, Хабр! Ранее я писал о том, как можно подружить разработчика и писателя в рамках единого процесса и о подходе Docs-as-code к документированию разработки. Здесь мне бы хотелось поразмышлять, как в условиях agile и постоянного развития одновременно перестраивать документирование под требования других процессов, зачастую не очень предсказуемых, и при этом сохранить максимальную целостность, качество и единообразие документации.

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

______________________________

3 меры для борьбы с бардаком в документировании

1. Зафиксировать жизненный цикл документации

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

В принципе, ЖЦ документации как явление рассматривался уже столько раз, что говорить о нем немного неуместно – можно просто открыть любую книгу или курс по документированию, ну, или форум техписателей. Ниже смотрите примерную структуру жизненного цикла, составленную на основе различных источников (Рисунок 1).

Рисунок 1. Жизненный цикл документации

Рисунок 1. Жизненный цикл документации

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

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

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

3. Разработать фирменный стандарт оформления документов

Да, сейчас можно сказать, что соответствие требованиям норм и стандартов – вещь весьма условная, и большинство организаций и предприятий, если они не принадлежат к категории оборонных, не требуют стопроцентного соответствия документов ГОСТам и другим стандартам. Но порядок то нужен, и с этим никто не поспорит. А ГОСТ – это наиболее упорядоченный свод требований. Да, он часто бывает запутан. Да, он бывает избыточен. Но мы сейчас не говорим о создании документа в соответствии со всеми требованиями по отступам, рамочкам, титулам и т. п. Для самостоятельной компании со своим отделом технических писателей и достаточно большим пакетом проектов и заказчиков просто необходим фирменный стандарт оформления внешних документов, в котором вполне можно предусмотреть основные моменты редакторской политики, графические средства и т. п. А вот в качестве основы для такого фирменного стандарта вполне может выступить отраслевой ГОСТ. Для нас, например, наиболее актуальны ГОСТы 34-й и 19-й серий. Причем, достаточно четко и понятно требования к содержанию и структуре документов прописаны именно в 34-й серии, конкретнее – в РД-50, который сейчас уже недействителен (отменен в 2019 году), но лучшего то ничего не придумали. Так почему бы не взять наиболее рациональные блоки по оформлению и структурированию документов оттуда и не переработать их в фирменную редполитику?

Еще один момент, о котором не стоит забывать, – многие наши заказчики работают (или когда-то работали) строго по обозначенным выше ГОСТам, и часто спрашивают, даже полубессознательно, о соответствии именно этим требованиям. Или же, даже если нет необходимости следовать ГОСТам, заказчикам все равно нужны более или менее четкие критерии для приемки. А где они их возьмут? Да все там же – в ГОСТах. Вот и получается, что даже декларируя отсутствие требований, мы все равно вынуждены им следовать хотя бы в общих чертах. Поверьте, это лучше, чем когда заказчик руководствуется принципом «я художник – я так вижу». Документацию при таком подходе можно сдавать долго и нудно. А уж какие при этом будут понесены потери!

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

Итак, на основе четких требований к документации и прозрачного жизненного цикла мы можем примирить всех – разработчиков, заказчиков и писателей. Ну или хотя бы снизить градус напряженности при принятии документации на продукты. Заодно это поможет навести порядок в структуре документов. О структуре, пожалуй, стоит написать отдельную статью, и не одну, но здесь в качестве «введения в предмет» давайте хотя бы галопом пробежимся по требованиям к основным документам.

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

Требования к структуре документации.  Введение в предмет

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

  1. Функциональное описание сервиса или приложения с архитектурными схемами и другой информацией.

  2. Файл Readme.

  3. Changelog.

  4. Описание (спецификация) API.

  5. Руководство по развертыванию.

  6. Руководство администратора.

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

  8. Руководство программиста (это скорее опция, т. к. требуется только в тех случаях, когда продукт позиционируется как платформа для дальнейшей разработки собственных приложений и сервисов. Наш продукт – платформа ZIIoT – относится к таковым).

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

Формировать перечень документов можно по простейшему алгоритму – смотрите Рис.  2.

Рисунок 2. Алгоритм формирования структуры внешней документации

Рисунок 2. Алгоритм формирования структуры внешней документации

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

Функциональное описание

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

Обычно в функциональное описание включаются следующие разделы (в соответствии с ГОСТ 19.402-78):

  1. Общие сведения (обозначение и наименование приложения, зависимости и взаимодействующее ПО и сервисы, языки программирования).

  2. Функциональное назначение (назначение программы и сведения о функциональных ограничениях на применение).

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

  4. Технические средства (требования к компьютерному обеспечению, на котором должно работать ПО).

  5. Вызов и загрузка.

  6. Формат данных на входе и на выходе.

Readme

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

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

  1. Полное наименование приложения/сервиса.

  2. Краткое описание.

  3. Использованные при разработке технологии и кодовая база.

  4. Установка и настройка программы, необходимые переменные и т. п.

  5. Характерные особенности, которые могут проявиться при работе с программой.

  6. Демо (изображения, ссылки на видео, интерактивные демо-ссылки).

Changelog

Журнал изменений или changelog – это файл, в котором содержатся все значимые изменения для каждой версии ПО. Эти изменения упорядочены, расположены в хронологическом порядке и в идеале всегда актуальны. Идеально, если журнал изменений генерируется автоматически. Тогда команде не приходится заморачиваться при каждом изменении в проекте – все они будут автоматически отражены в журнале.

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

Описание API

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

Руководство по развертыванию

Данный вид документа достаточно специфический и составляется командой системных инженеров. Технический писатель здесь может помочь разве что с оформлением текста более читабельным языком. Наши заказчики обычно хотят видеть в этом документе такие сведения, как:

  1. Возможные (типовые) конфигурации системы.

  2. Пошаговый порядок развертывания каждой типовой конфигурации.

  3. Порядок проверки работоспособности системы, полученной после установки.

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

Руководство администратора

 Руководство администратора помогает пользователям, ответственным за администрирование системы, следить за порядком ее работы, управлять доступом к ней, корректировать данные и так далее.  По ГОСТу (РД-50), руководство администратора должно включать:

  1. Назначение и порядок использования программного продукта.

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

  3. Администраторские обязанности и связанные с ними операции.

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

  5. Перечень мероприятий по обслуживанию системы с указанием порядка проведения:

    • настройка и параметризация;

    • справочно-нормативные данные;

    • описание управления учетными записями;

    • способы назначения прав доступа;

    • ввод и вывод информации;

    • описания возможных проблем или неполадок функционирования системы, методов их устранения.

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

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

Основные разделы руководства пользователя по РД-50:

1) Введение.

2) Назначение и условия применения.

3) Подготовка к работе.

4) Описание операций.

5) Аварийные ситуации.

6) Рекомендации по устранению проблем.

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

Следует заметить, что для руководств программиста и оператора нет такой уж богатой нормативной базы – каждый заказчик предъявляет к ним свои требования в зависимости от собственных «хотелок» и нужд. Но разрабатывать правила для таких документов все равно нужно. В частности, сейчас мы работаем над руководством программиста, оно, само собой, вызывает много споров и разногласий. В одной из следующих статей поделюсь с вами, к чему мы в результате придем и какие требования сформируем. Особенности руководства оператора мы тоже в перспективе раскроем.

А где же боль и как ее облегчить?

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

  • планирование осуществляется стихийно;

  • писатель не является полноценным участником процесса разработки, а выступает в качестве этакой пишущей машинки;

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

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

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

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

P.P.S. Отдельно хочу отметить, что в данной статье речь идет о формировании документации для «кондовых» технологических предприятий, работающих по ГОСТам. За время написания материала у нас наступило «прозрение», и мы поняли, что организация документации в виде длинных и нудных простыней, уходящих куда-то под стол (за рамки экрана ПК), видимо, не есть лучшее решение, и надо что-то менять в нашей жизни. Мы проработали новую структуру документации, оптимизировав ее в соответствии с требованиями docops и технологических норм, но это уже совсем другая история…

Источник

Если кроме использования и настройки, программное обеспечение предоставляет возможность написания, редактирования или использования программного кода. Какой документ необходим в этом случае?

Руководство программиста

Назначение руководства программиста

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

Примерами могут служить:

– библиотека функций;

– платформа или среда для разработки ПО;

– ПО с открытым кодом.

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

– назначение, структуру входных и выходных данных программных функций;

– возможности по созданию программного кода, особенности его интерпретации и компиляции;

– синтаксические особенности используемого языка программирования;

– возможные правила и ограничения при работе с программным кодом;

– различные инструкции по работе с программой.

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

Состав типового руководства программиста

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

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

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

– Обращение к программе, где указывают способы и параметры запуска программы;

– Входные и выходные данные, где описывают формат, способ организации и другие требования к входным и выходным данным;

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

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

Стандарты для руководства программиста

ГОСТы регламентируют и этот документ, в данном случае это ГОСТ 19.504. В соответствии с ним определяется структура и содержание Руководства программиста.

Заключение

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

– разработка руководства администратора;
– создание руководства пользователя;
– разработка руководства оператора.

Источник

ГОСТ 19.504-79

Группа Т55

МЕЖГОСУДАРСТВЕННЫЙ СТАНДАРТ

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

РУКОВОДСТВО ПРОГРАММИСТА

Требования к содержанию и оформлению

Unified system for program documentation. Programmer»s guide. Requirements for contents and form of presentation

МКС 35.080

Дата введения 1980-01-01

Постановлением Государственного комитета CCCР по стандартам от 12 января 1979 г. N 74 дата введения установлена 01.01.80

ИЗДАНИЕ (январь 2010 г.) с Изменением N 1, утвержденным в сентябре 1981 г. (ИУС 11-81).

Настоящий стандарт устанавливает требования к содержанию и оформлению программного документа «Руководство программиста», определенного ГОСТ 19.101-77 .

Стандарт полностью соответствует СТ СЭВ 2095-80*.
________________
* Доступ к международным и зарубежным документам, упомянутым в тексте, можно получить, обратившись в Службу поддержки пользователей . — Примечание изготовителя базы данных.

(Измененная редакция, Изм. N 1).

1. ОБЩИЕ ПОЛОЖЕНИЯ

1. ОБЩИЕ ПОЛОЖЕНИЯ

1.1. Структура и оформление документа устанавливаются в соответствии с ГОСТ 19.105-78 .

Составление информационной части (аннотации и содержания) является обязательным.

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

назначение и условия применения программы;

характеристики программы;

обращение к программе;

входные и выходные данные;

сообщения.

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

2.1. В разделе «Назначение и условия применения программы» должны быть указаны назначение и функции, выполняемые программой, условия, необходимые для выполнения программы (объем оперативной памяти, требования к составу и параметрам периферийных устройств, требования к программному обеспечению и т.п.).

2.2. В разделе «Характеристики программы» должно быть приведено описание основных характеристик и особенностей программы (временные характеристики, режим работы, средства контроля правильности выполнения и самовосстанавливаемости программы и т.п.).

2.3. В разделе «Обращение к программе» должно быть приведено описание процедур вызова программы (способы передачи управления и параметров данных и др.).

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

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

2.6. В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.).

Электронный текст документа
подготовлен АО «Кодекс» и сверен по:
официальное издание
Единая система программной документации:
Сборник национальных стандартов. —
М.: Стандартинформ, 2010

Г О С У Д А Р С Т В Е Н Н Ы Й С Т А Н Д А Р Т С О Ю З А С С Р

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

ГОСТ 19.504-79

(СТ СЭВ 2095-80)

РУКОВОДСТВО ПРОГРАММИСТА.
ТРЕБОВАНИЯ К СОДЕРЖАНИЮ И ОФОРМЛЕНИЮ

United system for program documentation.
Programmer»s guide. Requirements to contents and form of presentation

Постановлением Государственного комитета стандартов Совета Министров СССР от 12 января 1979 г. ¹ 74 срок введения установлен

с 01.01. 1980 г.

Настоящий стандарт устанавливает требования к содержанию и оформлению программного документа «Руководство программиста», определённого ГОСТ 19.101-77 .

Стандарт полностью соответствует СТ СЭВ 2095-80.

1. ОБЩИЕ ПОЛОЖЕНИЯ

1.1. Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78 .

Составление информационной части (аннотации и содержания) является обязательным.

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

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

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

2.1. В разделе «Назначение и условия применения программ» должны быть указаны назначение и функции, выполняемые программой, условия, необходимые для выполнения программы (объем оперативной памяти, требования к составу и параметрам периферийных устройств, требования к программного обеспечению и т.п.).

2.2. В разделе «Характеристика программы» должно быть приведено описание основных характеристик и особенностей программы (временные характеристики, режим работы, средства контроля правильности выполнения и самовосстанавливаемости программы и т.п.).

2.3. В разделе «Обращение к программе» должно быть приведено описание процедур вызова программы (способы передачи управления и параметров данных и др.).

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

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

2.6. В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.).

* Переиздание (Ноябрь 1987 г.) с Изменением № 1, утвержденным в сентябре 1981 г (ИУС 11-81)

Ниже представлен пример (образец) документа «Руководство пользователя
«, разработанного на основании методических указаний РД 50-34.698-90 .

Данный документ формируется IT-специалистом, или функциональным специалистом, или техническим писателем в ходе разработки рабочей документации на систему и её части на стадии «Рабочая документация».

Для формирования руководства пользователя в качестве примера был взят инструмент Oracle Discoverer
 информационно-аналитической системы «Корпоративное хранилище данных».

Ниже приведен состав руководства пользователя в соответствии с ГОСТ. Внутри каждого из разделов кратко приведены требования к содержанию и текст примера заполнения
 (выделен вертикальной чертой).

Разделы руководства пользователя:

1. Введение

В разделе «Введение» указывают:

  1. область применения;
  2. краткое описание возможностей;
  3. уровень подготовки пользователя;
  4. перечень эксплуатационной документации, с которой необходимо ознакомиться пользователю.

1.1. Область применения

Требования настоящего документа применяются при:

  • предварительных комплексных испытаниях;
  • опытной эксплуатации;
  • приемочных испытаниях;
  • промышленной эксплуатации.

1.2. Краткое описание возможностей

Информационно-аналитическая система Корпоративное Хранилище Данных (ИАС КХД) предназначена для оптимизации технологии принятия тактических и стратегических управленческих решений конечными бизнес-пользователями на основе информации о всех аспектах финансово-хозяйственной деятельности Компании.

ИАС КХД предоставляет возможность работы с регламентированной и нерегламентированной отчетностью.

При работе с отчетностью используется инструмент пользователя Oracle Discoverer Plus, который предоставляет следующие возможности:

  • формирование табличных и кросс-табличных отчетов;
  • построение различных диаграмм;
  • экспорт и импорт результатов анализа;
  • печать результатов анализа;
  • распространение результатов анализа.

1.3. Уровень подготовки пользователя

Пользователь ИАС КХД должен иметь опыт работы с ОС MS Windows (95/98/NT/2000/XP), навык работы с ПО Internet Explorer, Oracle Discoverer, а также обладать следующими знаниями:

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

Квалификация пользователя должна позволять:

  • формировать отчеты в Oracle Discoverer Plus;
  • осуществлять анализ данных.

1.4. Перечень эксплуатационной документации, с которой необходимо ознакомиться пользователю

  • Информационно-аналитическая система «Корпоративное хранилище данных». ПАСПОРТ;
  • Информационно-аналитическая система «Корпоративное хранилище данных». ОБЩЕЕ ОПИСАНИЕ СИСТЕМЫ.

2. Назначение и условия применения Oracle Discoverer Plus

В разделе «Назначение и условия применения» указывают:

  1. виды деятельности, функции, для автоматизации которых предназначено данное средство автоматизации;
  2. условия, при соблюдении (выполнении, наступлении) которых обеспечивается применение средства автоматизации в соответствии с назначением (например, вид ЭВМ и конфигурация технических средств, операционная среда и общесистемные программные средства, входная информация, носители данных, база данных, требования к подготовке специалистов и т. п.).

Oracle Discoverer Plus в составе ИАС КХД предназначен для автоматизации подготовки, настройки отчетных форм по показателям деятельности, а также для углубленного исследования данных на основе корпоративной информации хранилища данных.

Работа с Oracle Discoverer Plus в составе ИАС КХД возможна всегда, когда есть необходимость в получении информации для анализа, контроля, мониторинга и принятия решений на ее основе.

Работа с Oracle Discoverer Plus в составе ИАС КХД доступна всем пользователям с установленными правами доступа.

3. Подготовка к работе

В разделе «Подготовка к работе» указывают:

  1. состав и содержание дистрибутивного носителя данных;
  2. порядок загрузки данных и программ;
  3. порядок проверки работоспособности.

3.1. Состав и содержание дистрибутивного носителя данных

Для работы с ИАС КХД необходимо следующее программное обеспечение:

  1. Internet Explorer (входит в состав операционной системы Windows);
  2. Oracle JInitiator устанавливается автоматически при первом обращении пользователя к ИАС КХД.

3.2. Порядок загрузки данных и программ

Перед началом работы с ИАС КХД на рабочем месте пользователя необходимо выполнить следующие действия:

  1. Необходимо зайти на сайт ИАС КХД ias-dwh.ru.
  2. Во время загрузки в появившемся окне «Предупреждение о безопасности», которое будет содержать следующее: «Хотите установить и выполнить «Oracle JInitiator» …» Нажимаем на кнопку «Да».
  3. После чего запуститься установка Oracle JInitiator на Ваш компьютер. Выбираем кнопку Next и затем OK.

3.3. Порядок проверки работоспособности

Для проверки доступности ИАС КХД с рабочего места пользователя необходимо выполнить следующие действия:

  1. Открыть Internet Explorer, для этого необходимо кликнуть по ярлыку «Internet Explorer» на рабочем столе или вызвать из меню «Пуск».
  2. Ввести в адресную строку Internet Explorer адрес: ias-dwh.ru и нажать «Переход».
  3. В форме аутентификации ввести пользовательский логин и пароль. Нажать кнопку «Далее».
  4. Убедиться, что в окне открылось приложение Oracle Discoverer Plus.

В случае если приложение Oracle Discoverer Plus не запускается, то следует обратиться в службу поддержки.

4. Описание операций

В разделе «Описание операций» указывают:

  1. описание всех выполняемых функций, задач, комплексов задач, процедур;
  2. описание операций технологического процесса обработки данных, необходимых для выполнения функций, комплексов задач (задач), процедур.

Для каждой операции обработки данных указывают:

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

4.1. Выполняемые функции и задачи

Oracle Discoverer Plus в составе ИАС КХД выполняет функции и задачи, приведенные в таблице ниже:

4.2. Описание операций технологического процесса обработки данных, необходимых для выполнения задач

Ниже приведено описание пользовательских операций для выполнения каждой из задач.

Задача: «Визуализация отчетности»

Операция 1: Регистрация на портале ИАС КХД

  1. Компьютер пользователя подключен к корпоративной сети.
  2. Портал ИАС КХД доступен.
  3. ИАС КХД функционирует в штатном режиме.

Подготовительные действия:

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

  1. На иконке «ИАС КХД» рабочего стола произвести двойной щелчок левой кнопкой мышки.
  2. В открывшемся окне в поле «Логин» ввести имя пользователя, в поле «Пароль» ввести пароль пользователя. Нажать кнопку «Далее».

Заключительные действия:

Не требуются.

15-30 секунд.

Операция 2: Выбор отчета

Условия, при соблюдении которых возможно выполнение операции:

Успешная регистрация на Портале ИАС КХД.

Подготовительные действия:

Не требуются.

Основные действия в требуемой последовательности:

1. В появившемся окне «Мастер создания рабочих книг» поставить точку напротив пункта «Открыть существующую рабочую книгу».

2. Выбрать нужную рабочую книгу и нажать кнопку «Откр.»:

Заключительные действия:

После завершения работы с отчетом необходимо выбрать пункт меню «Файл», далее выбрать пункт «Закрыть».

Ресурсы, расходуемые на операцию:

15 секунд.

Задача: «Формирование табличных и графических форм отчетности»

Заполняется по аналогии.

5. Аварийные ситуации

В разделе «Аварийные ситуации» указывают: 1. действия в случае несоблюдения условий выполнения технологического процесса, в том числе при длительных отказах технических средств; 2. действия по восстановлению программ и/или данных при отказе магнитных носителей или обнаружении ошибок в данных; 3. действия в случаях обнаружении несанкционированного вмешательства в данные; 4. действия в других аварийных ситуациях.

В случае возникновения ошибок при работе ИАС КХД, не описанных ниже в данном разделе, необходимо обращаться к сотруднику подразделения технической поддержки ДИТ (HelpDesk) либо к ответственному Администратору ИАС КХД.

Класс ошибки Ошибка Описание ошибки Требуемые действия пользователя при возникновении ошибки
Портал ИАС КХД Сервер не найден. Невозможно отобразить страницу Возможны проблемы с сетью или с доступом к порталу ИАС КХД. Для устранения проблем с сетью обратиться к сотруднику подразделения технической поддержки (HelpDesk). В других случаях к администратору ИАС КХД.
Ошибка: Требуется ввести действительное имя пользователя При регистрации на портале ИАС КХД не введено имя пользователя. Ввести имя пользователя.
Ошибка: Требуется ввести пароль для регистрации При регистрации на портале ИАС КХД не введен пароль. Ввести пароль.
Ошибка: Сбой аутентификации. Повторите попытку Неверно введено имя пользователя или пароль, либо такая учетная запись не зарегистрирована. Нужно повторить ввод имени пользователя и пароля, однако после третей неудачной попытки регистрации учетная запись блокируется. Если учетная запись заблокирована, нужно обратиться к администратору ИАС КХД.
Сбой в электропитании рабочей станции Нет электропитания рабочей станции или произошел сбой в электропитании. Рабочая станция выключилась или перезагрузилась.

— нажать кнопку «Пуск»
— выбрать пункт «Выполнить»

Повторить попытку подключения (входа) в ИАС КХД

Сбой локальной сети Нет сетевого взаимодействия между рабочей станцией и сервером приложений ИАС КХД Отсутствует возможность начала (продолжения) работы с ИАС КХД. Нет сетевого подключения к серверу ИАС КХД Перезагрузить рабочую станцию.
Проверить доступность сервера ИАС КХД по порту 80, выполнив следующие команды:
— нажать кнопку «Пуск»
— выбрать пункт «Выполнить»
— в строке ввода набрать команду telnet ias_dwh.ru 80
— если открылось окно Telnet, значит соединение возможно.
После восстановления работы локальной сети повторить попытку подключения (входа) в ИАС КХД.

Ковтун М.В. Январь 2012.

Отправить свою хорошую работу в базу знаний просто. Используйте форму, расположенную ниже

Студенты, аспиранты, молодые ученые, использующие базу знаний в своей учебе и работе, будут вам очень благодарны.

Размещено на http://www.allbest.ru/

Руководство программиста

  • 1. Назначение и условия применения
  • 2. Характеристика программы
  • 3. Обращение к программе
  • 4. Полный перечень модулей и компонентов
  • 5. Сообщение пользователю

1
.
 Назначение и условия применения

Данный программный продукт может быть использован непосредственно для осуществления деятельности в организации «Проф&Элит», которая занимается установкой пластиковых конструкций, в том числе окон. программный пластиковый оконо

Программный продукт «Проф&Элит» служит для сбора информации о клиентах, сотрудниках, данных замеров для изготовления и производства изделий. Обеспечивает централизованное хранение данных. Продукт обладает простым и понятным интерфейсом, поэтому у пользователя не будет проблем в его освоении.

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

Требования к аппаратному обеспечению:

· процессор Intel Pentium
IV и выше;

· оперативная память 512 Мб и выше;

· видеокарта AGP/PCI Express 64 Мб и выше;

· свободное пространство на диске 12 Мб;

· видеомонитор с разрешением 1024×768;

· клавиатура;

· мышь;

· принтер для вывода на печать отчетов;

· операционная система Windows 98/2000/XP/Vista/7/8;

· Microsoft Access, Borland Delphi 7.

2
.
 Характеристика программы

В тестовом режиме был произведен запрос к форме ввода/вывода и введены данные в главную таблицу, что позволило оценить наглядно загруженность центрального процессора (ЦП) и использование выделенной (виртуальной) памяти с помощью «Диспетчера задач», как изображено на рис.Б.1 и рис.Б.2.

Рис.Б.2- Выделенная память и время загрузки

3
.
 Обращение к программе

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

Запустить данную программу можно непосредственно через оболочку Delphi. Для этого требуется открыть файл проекта Project1.dbr, находящемся в каталоге с программой. Далее, нажав F9, скомпилировать и запустить приложение.

Возможен запуск программы через командную строку. Запустить командную строку «Пуск/Все программы/Стандартные/Командная строка» Далее в командной строке необходимо ввести полный путь к программе, далее написать название программы (Project1.exe) и нажать Enter. Программа запущена.

Еще один способ запуска программы: в меню «Пуск» выберите пункт «Выполнить». В результате на экране откроется окно «Выполнение программы». В поле «Открыть» окна «Выполнение программы» введите путь к файлу программы, которую требуется запустить.

Выход из приложения возможен при нажатии на кнопку «Закрыть» или с помощью пункта меню программы «Файл/Выход», а также можно воспользоваться сочетанием клавиш Alt+F4.

4
.
 Полный перечень модулей и компонентов

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

В состав данного программного продукта входят следующие модули:

Unit1.pas — главный модуль программы, где непосредственно происходит заполнение данных по заказам;

Unit2.pas — отправка заказа дилеру (дилерский терминал);

Unit3.pas — модуль программы, где происходит заполнение данных по замерам изделия (окна);

Unit4.pas — модуль программы, где происходит заполнение данных по установке изделия (окна);

Unit5.pas — поиск, фильтрация, сортировка по заказам;

Unit6.pas — модуль «О программе».

В главной форме имеются компоненты, изображенные на рис.Б.3. На рисунке также изображено «дерево» всех компонентов формы (рис. Б.4).

Рисунок Б.3 — Компоненты главной формы

Компоненты главной формы:

TADOConnection — используется для указания базы данных и работы транзакциями;

TADOTable — таблица доступная через ADO;

DataSource обеспечивает механизм для связи компонентов доступа к данным (Table) с визуальными компонентами, которые отображают данные (DBGrid, DBEdit, DBListBox и т. д.)

TADOQuery — выполняет запрос (выборку) к базе данных;

TMainMenu — создает главное меню программы;

TDBGrid — осуществляет отображение данных из базы данных в виде таблицы;

TEdit — поле для ввода текстовых сообщений;

TButton — кнопка;

TComboBox — выпадающий список;

TDBCtrlGrid — используется для отображения таблицы в виде «кирпичиков»;

TLabel — надписи;

TGroupBox — панель, как отельный элемент с другими компонентами;

TDBNavigator — компонент для управления навигацией и редактированием данных;

TDBEdit — поле редактирования записи базы данных;

TDateTimePicker — выбор даты;

TSpeedButton — быстрая кнопка;

TBitBtn — кнопка, передающая действие форме;

TBevel — предназначен в приложении для простого обведения чего-либо рамкой.

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

Рисунок Б.4 — Структура компонентов

5
.
 Сообщение пользователю

Если пользователь ввёл неверные значения для фильтрации данных базы данных, то выводится сообщение, показанное на рис.Б.5.

Рис.Б.5 — Сообщение об ошибке

Если произошла ошибка при удалении данных, то выводиться сообщение об ошибке, показанное на рис.Б.6.

программный пластиковый окно

Рис.Б.6 — Сообщение об ошибке.

Пользователь забыл ввести номер накладной при сохранении заказа, то выводиться сообщение об ошибке, показанное на рис.Б.7.

Рис.Б.7 — Сообщение о ошибке

При попытке удаления выводится сообщение, показанное на рис.Б.8.

Рис.Б.8 — Диалог с пользователем

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

Рис.Б.9 — Диалог с пользователем

Размещено на Allbest.ru

…

Подобные документы

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

    курсовая работа , добавлен 19.03.2010

    Использование основных свойств объектно-ориентированного языка программирования C ++ при написании программы по реализации списка футболистов разных амплуа. Руководство пользователя и руководство программиста. Работа со списком, программный интерфейс.

    курсовая работа , добавлен 20.07.2014

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

    курсовая работа , добавлен 27.06.2015

    Особенности алгоритмов, критерии качества. Создание и применение программного продукта на языке Delphi. Тип операционной системы. Внутренняя структура программного продукта. Руководство пользователя и программиста, расчет себестоимости и цены программы.

    дипломная работа , добавлен 12.06.2009

    Delphi как программный продукт с феноменальными характеристиками. Компилятор в машинный код. Объектно-ориентированная модель программных компонентов. Масштабируемые средства для построения баз данных. Программный код.

    контрольная работа , добавлен 30.07.2007

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

    дипломная работа , добавлен 11.06.2012

    Назначение и область применения промышленных роботов. Разработка программы «Кинематическое движение» в среде Delphi для определения основных параметров кинематического движения. Описание работы и листинг программы. Руководство программиста и оператора.

    курсовая работа , добавлен 17.11.2014

    Техническое задание. Планы работы: первоначальный, поэтапный. Технический проект. Таблицы базы данных программы. Схема обмена данными. Тестирование программного продукта. Эксплуатационная документация. Руководство программиста. Руководство пользователя.

    курсовая работа , добавлен 07.12.2007

    Создание программного продукта по теме «Назначение и основные свойства палитры компонентов «Standard»», тестирующего знания студентов, в среде языка программирования Delphi. Особенности методики осуществления контроля знаний и состав тестовых заданий.

    курсовая работа , добавлен 17.04.2011

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

Создан 02.02.2010 9:34:31

Назначение и условия применения программ

В разделе «Назначение и условия применения программ» должны быть указаны назначение и, условия, необходимые для выполнения программы (объем, к составу и параметрам, требования к и т.п.) [из п. 2.1 ГОСТ 19.504-79]

Характеристика программы

В разделе «Характеристика программы» должно быть приведено описание основных характеристик и особенностей программы (временные характеристики, режим работы, средства контроля выполнения и самовосстанавливаемости программы и т.п.) [из п. 2.2 ГОСТ 19.504-79]

Обращение к программе

В разделе «Обращение к программе» должно быть приведено описание процедур вызова программы (способы передачи управления и параметров данных и др.) [из п. 2.3 ГОСТ 19.504-79]

Входные и выходные данные

В разделе «Входные и выходные данные» должно быть приведено описание организации используемой входной и выходной информации и, при необходимости, ее [из п. 2.4 ГОСТ 19.504-79]

Сообщения

В разделе «Сообщения» должны быть указаны тексты сообщений, выдаваемых программисту или в ходе выполнения программы, описание их содержания и действий, которые необходимо предпринять по этим сообщениям [из п. 2.5 ГОСТ 19.504-79]

Приложения

В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.) [из п. 2.6 ГОСТ 19.504-79]

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

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

СИСТЕМА УПРАВЛЕНИЯ ДЛЯ УЧАСТКА СБОРКИ И НАСТРОЙКИ ДВДТ

АННОТАЦИЯ

В данном руководстве содержится информация, описывающая прикладное программное обеспечение для участка сборки и настройки ДВДТ – участок ДВДТ (далее по тексту – участок). Документ содержит информацию о доступе к функциям системы управления MasterScada (далее по тексту – СУ), структуре программы, методики записи и просмотра произошедших событий.

СОДЕРЖАНИЕ

1             НАЗНАЧЕНИЕ И УСЛОВИЯ ПРИМЕНЕНИЯ ПРОГРАММЫ           5

1.1          Назначение программы            5

1.2          Аппаратные средства  6

2             ХАРАКТЕРИСТИКА ПРОГРАММЫ          7

2.1          Структура SQL базы данных    7

2.2          Программные секции 10

2.3          Структура программного обеспечения            14

3             ОБРАЩЕНИЕ К ПРОГРАММЕ   16

4             ВХОДНЫЕ И ВЫХОДНЫЕ ДАННЫЕ        16

5             СООБЩЕНИЯ    17

ПЕРЕЧЕНЬ ТЕРМИНОВ И ОПРЕДЕЛЕНИЙ           18

ПЕРЕЧЕНЬ СОКРАЩЕНИЙ          19

ПЕРЕЧЕНЬ РИСУНКОВ 20

ПЕРЕЧЕНЬ ТАБЛИЦ       21

ПЕРЕЧЕНЬ ССЫЛОЧНЫХ ДОКУМЕНТОВ              22

ЛИСТ РЕГИСТРАЦИИ ИЗМЕНЕНИЙ       23

1             НАЗНАЧЕНИЕ И УСЛОВИЯ ПРИМЕНЕНИЯ ПРОГРАММЫ

1.1          Назначение программы

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

— настройка температуры;

— настройки давления;

— настройки скорости ветра;

— настройки влажности;

— настройки ДВДТ;

— сдачи ПСИ.

ПО реализует следующие функции:

— получение и обработка сигналов ввода-вывода с корзины ввода-вывода;

— приём и фильтрация входных дискретных сигналов от вероятного «дребезга» контактов;

— приём и обработка входных аналоговых сигналов;

— контроль выхода сигнала за допустимые границы (недостоверность сигнала);

— масштабирование аналогового сигнала;

— генерация пороговых нарушений с функцией гистерезиса;

— выдача дискретных команд на оборудование (управляющие воздействия);

— реализация алгоритмов управления системой;

— реализация алгоритмов защит;

— обмен данными со смежными системами по протоколу Modbus TCP;

— диагностика модулей контроллера на наличие ошибок, и формирование сообщений для АРМ о состоянии оборудования контроллера;

— мониторинг аварийных ситуаций оборудования системы.

ПО реализует следующие функции:

— вывод на экран видеокадра текущего состояния участка;

— отображение состояний оборудования;

— управление механизмами установки;

— ведение архива собранных событий;

— отображение аварийных ситуаций;

— ведение хронологии аварийных событий.

1.2          Аппаратные средства

В состав технических средств системы входят следующие аппаратные и программные компоненты:

— Электронный модуль давления Метран-518 предназначен для точного измерения и непрерывного преобразования значений абсолютного и избыточного давления, разрежения, давления-разрежения при поверке и калибровке различных приборов давления;

— Камера ТБК-500;

— Контроллеры PACE5000 и РАСЕ1000;

— Мультиметр Метран-514МПП

Персональный компьютер ПЭВМ

— процессор не хуже Intel i7 2,7 ГГц

— слоты расширения на материнской плате, не менее: 5 слотов 1x PCI-E 2.0, 1 слот 16x PCI-E 3.0

— память не менее 16 Гб DDR4-2133/2400

— дисковая подсистема: корзина на 2 диска, 2,5” SSD не менее 240GB (для системы и программ), 3.5” HDD SATA не менее 1 Tb (для данных);

— оптический привод DVD±RW в комплекте;

— порты: 4 x USB 3.0; 6 x USB 2.0, VGA, DVI, 1x LAN (RJ-45, Ethernet 10/100/1000), 4x RS232, 4x CAN 2.0

— блок питания, не менее 600 Вт;

— рабочая температура от +5º до +40ºС (промышленное исполнение);

— поддержка работы с двумя мониторами одновременно.

Установлено лицензионное ПО: Microsoft Windows Server 2012,

В слоты расширения ПК установлены и подключены интерфейсные платы RS 232 CAN; соединители плат должны выведены на заднюю панель ПК

В состав ПК входит: системный блок, монитор 24-27” со входами DVI и VGA, клавиатура, манипулятор «мышь»

Дополнительно: коммутатор Ethernet.

2             ХАРАКТЕРИСТИКА ПРОГРАММЫ

2.1          Структура SQL базы данных

Потребность в СУРБД Microsoft SQL Server у пользователей ПО MasterScada может возникнуть только в тех случаях, когда предполагается использовать оперативные журналы или SQL базу данных телеметрии.

SQL база данных состоит из таблиц. Поля БД — это столбцы таблицы, а записи БД — это строки таблицы. Каждая БД изначально содержит таблицы:

— CONFORMS

— CORETABLE

— EQUIPMENT

— HISTORY

— MAGS

— NEXTNUMS

— PERSONS

— REFS

— SQLTOKENS

— USERFORMS.

Таблица CORETABLE состоит из наиболее распространенных полей, которые характерны почти для любого оперативного журнала:

— RECID                 — уникальный идентификатор записи;

— FULLPATH        — принадлежность записи конкретному журналу (путь в дереве журналов);

— DATACREATE — дата/время создания записи;

— DATE1, DATE2                — вспомогательные даты/времени общего назначения (например, обнаружения и устранения дефекта);

— OBJECT              — оборудование, к которому относится запись;

— COMMENT      — произвольный комментарий (например, описание дефекта);

— STATE                — состояние записи (например, обнаружен/устранен).

Каждая запись имеет свой жизненный цикл, который ведется в таблице HISTORY. Там фиксируются факты создания записи (кто, когда создал, редактировал, подписывал или отзывал подпись).

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

Рисунок 1 – Модель данных БД. Связи по внешнему ключу

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

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

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

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

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

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

Кроме обычных справочников, предусмотрен специальный вид справочника — справочник оборудования. Этот справочник представляет собой иерархическую структуру и отображается в виде дерева. Такой подход связан с тем, что одинаковое оборудование может располагаться на разных объектах. В данном справочнике предусмотрено хранение кодов оборудования согласно требованиям ОДУ. Справочник оборудования может быть привязан только к полю строкового типа.

Для каждого журнала могут быть созданы формы просмотра списком нескольких записей, просмотра/редактирования одной записи и печатных документов (отчет). Форма редактирования должна представлять собою максимально детализированное представление записи, именно с ее помощью (и только через нее) осуществляется редактирование записи. В случае если на данном уровне дерева какая-либо из форм не задана, берется форма из вышестоящего уровня. Все указанные формы обязательно должны быть созданы для всех журналов первого уровня! Формы и отчеты создаются в конфигураторе БД при помощи дизайнера форм и дизайнера отчетов.

2.2          Программные секции

Приложение содержит:

— конфигурацию аппаратных и программных средств;

— набор функциональных модулей, каждый из которых реализуется секциями, написанными на языке ST (структурированного текста);

— набор функциональных блоков, разработанных в рамках проекта KPC;

— базу данных переменных контроллера;

— анимационные таблицы.

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

Таблица 2.1 – Программные секции

Внутри секций используются следующие подпрограммы (функциональные блоки), которые приведены в таблице 2.2.

Таблица 2.2 – Функциональные блоки

Параметры сигналов блоков приведены в таблице 2.3.

Таблица 2.3 – Параметры сигналов блока

Разъём                Контакт               Наименование               Параметры

X1           1             I вх.       Токовый вход датчика температуры. I вх. не более 400 мкА.

                2                             Пустой вывод. Не использовать.

                3                             Пустой вывод. Не использовать.

                4             +12В      Выход напряжения питания датчика температуры 12±0,25 В относительно «Общ.12В» Ток нагрузки не более 400 мкА.

X3           1             +12В      Выход напряжения питания +12±0,25 В относительно «Общ.12В» Ток нагрузки не более 400 мкА.

                2             +7В        Выход напряжения питания +7±0,25 В относительно «Общ.» Ток нагрузки не более 300 мА.

                3             -7В         Выход напряжения питания -7±0,25 В относительно «Общ.» Ток нагрузки не более 50 мА.

                4             Общ.     Нулевой потенциал блока.

                5             Общ.     Нулевой потенциал блока.

                6             Общ.     Нулевой потенциал блока.

                7             CAN_L Линия цифровой сети передачи данных CAN-L. Параметры согласно ISO11898

                8             CAN_H Линия цифровой сети передачи данных CAN-Н. Параметры согласно ISO11898

X2           1             GND      Нулевой потенциал блока.

                2             RESET    Сигнал интерфейса JTAG.

                3             TMS       Сигнал интерфейса JTAG.

                4             TCK        Сигнал интерфейса JTAG.

                5             TDI         Сигнал интерфейса JTAG.

                6             TRST      Сигнал интерфейса JTAG.

                7                            

                8             3,3В       Напряжение питания 3,3В. Ток нагрузки не более 10 мА.

2.3          Структура программного обеспечения

Структура ПО представлена на рисунке 2.

Рисунок 2 – Структура ПО

Приложение содержит:

— таблицы настроечных параметров системных функций панели;

— набор скриптов, для реализации программных функций, написанными на языке JAVA;

— перечень видеокадров системы;

— перечень всплывающих окон в системе

— базу данных переменных тэгов панели.

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

Таблица 2.4 – Перечень скриптов

3             ОБРАЩЕНИЕ К ПРОГРАММЕ

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

Настройка параметров прикладного программного обеспечения операторской панели настраивается с ПК.

При этом настраиваются:

— таймеры нарушений работы стенда;

— уставки времени дискретных выходных сигналов;

— шкала входного аналогового сигнала температуры;

— шкала входного аналогового сигнала давления;

— шкала входного аналогового сигнала влажности;

— шкала входного аналогового сигнала скорости ветра;

— время цикла приложения;

— IP и Modbus адреса приборов стенда.

4             ВХОДНЫЕ И ВЫХОДНЫЕ ДАННЫЕ

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

Выходными данными системы является информация, передаваемая на объект управления (стенд) из ПК через устройство связи с объектом. Информация выводится в АРМ оператора в виде экранных форм.

5             СООБЩЕНИЯ

Сообщения, передаваемые по интерфейсу АРМ-стенд, приведены в таблице 5.1.

Таблица 5.1 – Перечень событий, выводимых в журнале событий

№ п/п Наименования события

1             Выбрана вкладка блока №1

2             Выбрана вкладка блока №2

3             Выбрана вкладка блока №3

4             Выбрана вкладка блока №4

5             Индикатор питание +7 В

6             Индикатор питание -7 В

7             Индикатор питание +12 В

8             ПК подключен к стенду

9             Нажата кнопка включения блока №1

10           Нажата кнопка включения блока №2

11           Нажата кнопка включения блока №3

12           Нажата кнопка включения блока №4

13           Индикатор включения блока №1

14           Индикатор включения блока №2

15           Индикатор включения блока №3

16           Индикатор включения блока №4

17           Нажата кнопка включения камеры

18           Индикатор включения камеры

19           Резерв

20           Повышенное напряжение между фазами

21           Индикатор отключения камеры

22           Команда на включение камеры

23           Команда на задание скорости ветра

24           Команда на отключение блока №1

25           Команда на отключение блока №2

26           Команда на отключение блока №3

27           Команда на отключение блока №4

ПЕРЕЧЕНЬ ТЕРМИНОВ И ОПРЕДЕЛЕНИЙ

Автоматизированная система (АС) – система, состоящая из персонала и комплекса средств автоматизации его деятельности, реализующая информационную технологию выполнения установленных функций.

База данных (БД) – представленная в объективной форме совокупность самостоятельных материалов (статей, расчётов, нормативных актов, судебных решений и иных подобных материалов), систематизированных таким образом, чтобы эти материалы могли быть найдены и обработаны с помощью электронной вычислительной машины (ЭВМ).

Система управления базами данных (СУБД) – совокупность программных и лингвистических средств общего или специального назначения, обеспечивающих управление созданием и использованием БД.

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

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

MasterScada – программный пакет для проектирования систем диспетчерского управления и сбора данных (Scada).

SQL – язык программирования, применяемый для создания, модификации и управления данными в реляционной базе данных, управляемой соответствующей системой управления базами данных,

ПЕРЕЧЕНЬ СОКРАЩЕНИЙ

SCADA (Supervisory Control and Data Acquisition System) – система диспетчерского управления и сбора данных

АС          – автоматизированная система;

БД          – база данных;

ПК          – персональный компьютер;

ПО         – программное обеспечение;

СУ          – система управления;

СУБД    – система управления базами данных.

ПЕРЕЧЕНЬ РИСУНКОВ

Рисунок 1 – Модель данных БД. Связи по внешнему ключу 8

Рисунок 2 – Структура ПО         13

ПЕРЕЧЕНЬ ТАБЛИЦ

Таблица 2.1 – Программные секции   10

Таблица 2.2 – Функциональные блоки             12

Таблица 2.3 – Параметры сигналов блока       12

Таблица 2.4 – Перечень скриптов        15

Таблица 5.1 – Перечень событий, выводимых в журнале событий 17

ПЕРЕЧЕНЬ ССЫЛОЧНЫХ ДОКУМЕНТОВ

№ п/п Нормативный документ

1             ГОСТ 19781-90 ЕСПД. Термины и определения.

2             ГОСТ 19.105-78. ЕСПД. Общие требования к программным документам.

3             ГОСТ 19.402-78. ЕСПД. Описание программы.

4             ГОСТ 19.504-79. ЕСПД. Руководство программиста. Требования к содержанию и оформлению.

5             ГОСТ 19.701-90. ЕСПД. Схемы алгоритмов, программ, данных и систем. Обозначения условные и правила выполнения

ЛИСТ РЕГИСТРАЦИИ ИЗМЕНЕНИЙ

#Руководствопрограммиста, #описание, #ПЛК, #ПТС, #интерфейс

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

  1. Назначение и
    условия применения программы.

  2. Характеристики
    программы.

  3. Обращение к
    программе.

  4. Входные и выходные
    данные.

  5. Сообщения.

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

В
разделе Характеристики
программы необходимо
привести описание
основных характеристик и особенностей
программы: временных
характеристик, режима работы, средств
контроля правильности
выполнения и самовосстанавливаемости
программы и т.д.

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

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

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

Гост 19.505-79 еспд. Руководство оператора. Требования к содержанию и оформлению

Руководство
оператора должно включать:

  1. Назначение
    программы.

  2. Условия выполнения
    программы.

  3. Выполнение
    программы.

  4. Сообщения оператору.

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

Условия выполнения
программы должны
содержать условия, необходимые для
выполнения программы: минимальный и/или
максимальный состав аппаратурных и
программных средств.

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

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

Гост 19.506-79 еспд. Описание языка. Требования к содержанию и оформлению

При описании языка
необходимо указать:

  1. Общие сведения.

  2. Элементы языка.

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

  1. Способы
    структурирования программы.

  2. Средства обмена
    данными.

  3. Встроенные
    элементы.

  4. Средства отладки
    программы.

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

В разделе Элементы
языка приводят
описание синтаксиса и семантики базовых
и составных элементов языка.

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

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

В разделе Встроенные
элементы описываются
встроенные в
язык элементы: функции, классы и т.д. и
правила их использования.

При
описании средств
отладки необходимо
привести
описание имеющихся в языке средств
отладки программ, семантики этих средств,
дать рекомендации по их применению.

ГОСТ
Р ИСО/МЭК 9294-93. Информационная технология.
Руководство
по управлению документированием
программного обеспечения.
Стандарт
полностью соответствует международному
стандарту ИСО/МЭК 9294:1990 и устанавливает
рекомендации по эффективному управлению
документированием ПС для руководителей,
отвечающих за их создание. Целью стандарта
является оказание помощи в определении
стратегии документирования ПС; выборе
стандартов по документированию; выборе
процедур документирования; определении
необходимых ресурсов; составлении
планов документирования.

ГОСТ
Р ИСО/МЭК 9126-93. Информационная технология.
Оценка
программной продукции. Характеристики
качества и руководства
по их применению. Стандарт
полностью соответствует международному
стандарту ИСО/МЭК 9126:1991. В его контексте
под характеристикой качества понимается
«набор свойств (атрибутов) программной
продукции, по которым ее качество
описывается и оценивается». Стандарт
определяет шесть комплексных
характеристик, которые с минимальным
дублированием описывают
качество ПС (ПО, программной продукции):

  • функциональные
    возможности;

  • надежность;

  • практичность;

  • эффективность;

  • сопровождаемость;

  • мобильность.

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

ГОСТ
Р ИСО 9127-94. Системы обработки информации.
Документация
пользователя и информация на упаковке
для потребительских
программных пакетов. Стандарт
полностью соответствует
международному стандарту ИСО 9127:1989. В
контексте настоящего стандарта под
потребительским программным пакетом
(ПП) понимается «программная продукция,
спроектированная и продаваемая для
выполнения определенных функций;
программа и соответствующая ей
документация, упакованные для продажи
как единое целое». Под документацией
пользователя понимается документация,
которая обеспечивает конечного
пользователя информацией по установке
и эксплуатации ПП. Под информацией на
упаковке понимают информацию,
воспроизводимую на внешней
упаковке ПП. Ее целью является
предоставление потенциальным
покупателям первичных сведений о ПП.

ГОСТ
Р ИСО/МЭК 8631-94. Информационная технология.
Программные
конструктивы и условные обозначения
для их представления.
Описывает
представление процедурных алгоритмов.

Как
уже говорилось, пока нет лучшего, можно
извлекать пользу и
из тех стандартов ЕСПД, которые приняты
еще около 20 лет назад. Но всем ясно, что
ориентироваться надо на современные
стандарты.

Практики используют
еще один путь: сами переводят и используют
в своих проектах современные стандарты
на организацию ЖЦ ПС и их документирование.
Но этот путь страдает как минимум
тем недостатком, что разные переводы и
адаптации стандартов,
сделанные разными разработчиками и
заказчиками, будут отличаться массой
деталей. Эти отличия неизбежно касаются
не только наименований, но и их
содержательных определений, вводимых
и используемых в стандартах. Таким
образом, на этом пути неизбежно постоянное
возникновение путаницы, а это прямо
противоположно целям не только стандартов,
но и любых грамотных методических
документов [59].

ГОСТ
Р ИСО/МЭК 12119:1994. Информационная технология.
Пакеты
программных средств. Требования к
качеству
и испытания. В
этом стандарте установлены требования
к качеству пакетов программ и инструкции
по их испытаниям
на соответствие заданным требованиям.
Понятие «пакет программных средств»
фактически отождествляется
с более общим понятием «программный
продукт», рассматриваемым
как совокупность программ, процедур и
правил, поставляемых
нескольким пользователям для общего
применения или
функционирования. Каждый пакет программ
должен иметь описание
продукта и пользовательскую документацию.

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

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

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

В контексте данного
стандарта требования к качеству продукта
рассматриваются с точки зрения описания
реальных свойств продукта
в «Описании продукта» и пользовательской
документации. Требования к программам
и данным в основном сводятся к утверждению
необходимости соответствия реальных
свойств продукта
свойствам, объявленным в документации.
В связи с этим документ
формально не может рассматриваться как
стандарт требований. Несмотря на эту
ограниченность, стандарт может оказаться
весьма полезным при определении исходных
требований к продукту:

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

  • требования
    к описанию продукта. В частности,
    требования, согласно
    которому описание продукта должно
    содержать конкретную информацию, а все
    приводимые в нем формулировки должны
    быть проверяемыми (контролируемыми) и
    корректными;

  • требования к
    документации пользователя;

  • требования к любым
    программам и данным, входящим в состав
    пакета программ.

Описание
продукта. Описание
продукта (product
description):
документ,
определяющий свойства пакета программ,
основным назначением которого является
оказание помощи потенциальным покупателям
в оценке пригодности для них данного
продукта до его приобретения.

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

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

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

  1. Общие требования
    к содержанию.

  2. Обозначения и
    указания.

  3. Функциональные
    возможности.

  4. Надежность.

  5. Практичность.

  6. Эффективность.

  7. Сопровождаемость
    и мобильность.

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

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

  • быть внутренне
    непротиворечивым. Каждый термин должен
    иметь один и тот же смысл по всему
    документу;

  • формулировки
    должны быть проверяемыми и корректными.

При описании
продукта необходимо приводить следующие
указания
и
обозначения:

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

  1. Должны быть
    включены наименование и адрес поставщика.

  1. Должны быть
    определены целевые рабочие задачи,
    которые могут быть выполнены данным
    продуктом.

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

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

  • процессоры, включая
    сопроцессоры;

  • объем основной
    (оперативной) памяти;

  • типы и объемы
    (памяти) периферийных запоминающих
    устройств;

  • расширяющие платы;

  • оборудование
    ввода и вывода;

  • сетевое оборудование;

  • системные и прочие
    программные средства.

  1. Должны
    быть определены соответствующие
    интерфейсы или продукты,
    если в описании продукта имеются ссылки
    на интерфейсы с другими продуктами.

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

  3. Должен
    быть установлен вид поставляемых
    программ, например
    исходные программы, объектные (рабочие)
    модули или загрузочные модули.

  4. Должно быть
    указано, будет ли инсталляция продукта
    проводиться пользователем или нет.

  5. Должно быть
    указано, будет или не будет предлагаться
    поддержка при эксплуатации продукта.

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

При описании
функциональных
возможностей необходимо
отразить:

1.
Обзор
функций.

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

• продукта;

  • расширения
    продукта, полностью приведенного в
    описании продукта;

  • расширения
    продукта, на которое дана ссылка в
    описании продукта;

  • негарантируемого
    (необязательного) приложения.

2. Граничные
значения.

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

  • минимальные или
    максимальные значения;

  • длины ключей;

  • максимальное
    число записей в файле;

  • максимальное
    число критериев поиска;

  • минимальный объем
    выборки.

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

Соседние файлы в предмете [НЕСОРТИРОВАННОЕ]

  • #
  • #
  • #
  • #
  • #
  • #
  • #
  • #
  • #
  • #
  • #

Подборка по базе: организация как управляемая система.docx, Бюджетная система РФ Контрольная работа.doc, ЛПР МДК 05. 01 Проектирование и дизайн информационных систем.doc, «Внедрение цифровой информационной системы ФГИС «Моя школа» как , Сигнальные системы Павлова..docx, Реферат_уровневая система образования в РФ.docx, Теория информационных процессов и систем копия.pdf, Практическая работа № 2 (Часть 1) Раздел программы_ 2.1.4. Объек, Оценка системы материальной и нематериальной мотивации туристиче, Россия в системе международных отношений.docx

8. РАБОЧАЯ ДОКУМЕНТАЦИЯ
В состав рабочей, или иначе эксплуатационной, документации входят руководство пользователя, руководство оператора, руководство администратора, руководство системного администратора, руководство программиста, руководство системного программиста.
8.1. Руководство пользователя
Основной целью руководства пользователя является обеспечение пользователя необходимой информацией для самостоятельной работы с программой или автоматизированной системой. Поэтому руководство пользователя должно отвечать на вопросы:
 что это за программа (система)?
 что может программа (система)?
 что необходимо для обеспечения корректного функционирования программы (системы)?
 что делать в случае отказа системы?
При составлении наиболее подробного руководства пользователя можно придерживаться следующей структуры:
1. Введение
Данный раздел должен предоставлять пользователю общую информацию о программе (системе). В нем указывают:
 область применения;
 краткое описание возможностей;
 уровень подготовки пользователя.

51
2. Перечень эксплуатационной документации
В данном разделе перечисляется документация, которая позволит пользователю избежать определенного рода ошибок.
3. Назначение и условия применения
Раздел подразделяет основную задачу программы (системы) на подзадачи и описывает каждую из них. В нем указывают:
 виды деятельности, функции, для автоматизации которых предназначено данное средство автоматизации;
 условия, при соблюдении (выполнении, наступлении) которых обеспечивается применение средства автоматизации в соответствии с назначением (например, вид ЭВМ и конфигурация технических средств, операционная среда и общесистемные программные средства, входная информация, носители данных, база данных, требования к подготовке специалистов и т. п.).
4. Подготовка к работе
Данный раздел должен содержать пошаговую инструкцию для запуска программы (системы). К этапу подготовки системы к работе можно отнести установку дополнительных приложений, идентификацию, аутентификацию. В данном разделе указывают:
 состав и содержание дистрибутивного носителя данных;
 порядок загрузки данных и программ.
5. Проверка работоспособности
В разделе описываются показатели, по которым можно определить, что программное обеспечение работает нестабильно.
6. Описание операций
Это основной раздел, который содержит пошаговую инструкцию для выполнения того или иного действия пользователем. Если работа

52 автоматизированной системы затрагивает целый бизнес-процесс, то в руководстве пользователя перед описанием операций целесообразно предоставить информацию о данном процессе, его назначении и участниках. Подобное решение позволяет человеку четко представить свою роль в данном процессе и те функции, которые реализованы для него в системе. Далее в руководстве пользователя следует представить описание функций, разбитых на отдельные операции.
Необходимо выделить подразделы, описывающие функции данного процесса, и действия, которые необходимо совершить для их выполнения:
 описание всех выполняемых функций, задач, комплексов задач, процедур;
 описание операций технологического процесса обработки данных, необходимых для выполнения функций, задач, процедур.
7. Аварийные ситуации
В разделе описываются действия в случае длительных отказов технических средств, обнаружении несанкционированного вмешательства в данные, действия по восстановлению программ или данных.
8.2. Руководство оператора
Нормативной базой для составления данного документа может являться ГОСТ 19.505-79 «ЕСПД. Руководство оператора. Требования к содержанию и оформлению», в котором выделяются следующие разделы:
 назначение программы (сведения о назначении программы и информация, достаточная для понимания функций программы и ее эксплуатации);

53
 условия выполнения программы (минимальный и/или максимальный состав аппаратурных и программных средств и т. д.);
 выполнение программы
(последовательность действий оператора, обеспечивающих загрузку, запуск, выполнение и завершение программы, описание функций, формата и возможных вариантов команд, с помощью которых оператор осуществляет загрузку и управляет выполнением программы, а также ответы программы на эти команды);
 сообщения оператору (тексты сообщений, выдаваемых в ходе выполнения программы, описание их содержания и соответствующие действия оператора в случае сбоя, возможности повторного запуска программы и т. п.).
В зависимости от особенностей документа допускается объединять отдельные разделы или вводить новые. Допускается содержание разделов иллюстрировать поясняющими примерами, таблицами, схемами, графиками.
В общем случае руководство оператора отличается от руководства пользователя. В руководстве оператора все процессы, выполняемые программным обеспечением, рассматриваются с технической точки зрения. Исходя из этого, можно представить альтернативную структуру данного руководства:
1. Установка на сервер
В разделе описывается процесс установки программного обеспечения на сервер. Пошаговая инструкция дает точные указания, каким образом необходимо выполнить установку, в зависимости от технического состояния сервера.

54
2. Установка локальная
В разделе описывается процесс настройки компьютеров, использующих программное приложение, также даются рекомендации по оптимизации настройки рабочих станций, чтобы улучшить процесс взаимодействия сервера и компьютеров пользователей.
3. Администрирование пользователей
В разделе подробно описывается процесс администрирования учетных записей пользователей программного обеспечения.
Подробная инструкция описывает все ситуации, которые могут возникнуть при управлении пользователями. Например, можно централизованно завершать все активные соединения с информационной базой и устанавливать блокировку новых соединений на определенный период времени. Такая возможность полезна при выполнении различных административных действий с информационной базой.
4. Информационная база
В разделе рассматриваются вопросы администрирования, сохранения, переноса базы данных. Описаны рекомендации по настройке базы данных. Например, рассматривается ситуация резервного копирования. Резервное копирование может выполняться как в автоматическом режиме, так и в ручном. Для автоматического режима предварительно необходимо выполнить настройки. В любой момент можно восстановить данные информационной базы из созданной ранее резервной копии.
5. Технические неполадки
Этот раздел содержит информацию о возможных технических проблемах, которые могут возникнуть в процессе эксплуатации программного обеспечения.
Рассматриваются проблемы, возникающие в результате некорректной работы оборудования, а

55 также ситуации, возникающие в результате некорректного использования функций программного обеспечения.
6. Программный код
В разделе подробно описывается структура программного кода.
Если в процессе использования программного обеспечения возникают ошибки или потребуется доработка, то для этого необходимо знать программный код. Указываются особенности программного кода, создающие затруднения в процессе доработки. Раздел является очень важным, так как может потребоваться добавить, удалить или изменить определенные функции программного обеспечения.
8.3. Руководство администратора
Обычно администратор считается пользователем системы, при этом он наделен как особыми обязанностями, так и необходимыми для их выполнения привилегиями. По методике и стилю изложения руководство администратора похоже на руководство пользователя.
При этом, как правило, описание в нем строится от задач, а не от функций.
Работа администратора многопользовательской системы, как правило, заключается в управлении учетными записями других пользователей, предоставлении им полномочий на доступ к данным и выполнение операций, а также в исправлении сделанных ими ошибок.
Например, бывают автоматизированные системы, в которых вводить и редактировать данные может любой пользователь, а удалять – только администратор. Кроме того, администратор может заниматься ведением нормативно-справочной информации, загрузкой и выгрузкой данных, открытием и закрытием расчетных периодов и т. п. С этой точки зрения руководство администратора является системным документом и приобретает смысл только в условиях конкретной системы с живыми пользователями.

56
Системы часто создаются на основе тиражируемых программных продуктов или аппаратно-программных комплексов. В составе таких решений нередко поставляется программный компонент под названием «Администратор», предназначенный для управления системой после ее развертывания.
Структура руководства администратора существенным образом зависит от того, как устроена система, и какого обслуживания она требует.
Типичная структура руководства администратора системы следующая:
1. Назначение системы
2. Принципы функционирования системы
3. Обязанности и задачи администратора
4. Обслуживание системы
 настройка параметров работы системы;
 ведение нормативно-справочной информации;
 учетные записи пользователей и управление ими;
 назначение пользователям прав доступа;
 загрузка и выгрузка данных.
5. Проблемы в работе системы и способы их решения
Руководство по административному модулю программного или программно-аппаратного комплекса содержит примерно те же сведения, но в более общем виде. Например, в нем должно быть объяснено, как создать учетную запись пользователя, но не может быть указано, когда это следует делать. Такая конкретика возникает только при внедрении продукта в некотором конкретном месте и отражается в технологических инструкциях или регламентах.

57
Структура руководства по административному модулю программного или аппаратно-программного комплекса может иметь следующий вид:
1. Общие сведения о комплексе
2. Функционирование комплекса в рамках системы
(рассматриваются несколько наиболее типичных случаев применения комплекса и перечисляются основные обязанности администратора в каждом из них)
3. Интерфейс пользователя административного модуля
4. Задачи по обслуживанию
 настройка параметров работы системы;
 ведение нормативно-справочной информации;
 учетные записи пользователей и управление ими;
 назначение пользователям прав доступа;
 загрузка и выгрузка данных.
5. Типичные проблемы в работе и способы их решения
Руководство администратора не следует путать с руководством системного администратора. Первый документ говорит о том, как организовать и поддерживать целевое применение системы, второй – как обеспечить ее техническую работоспособность.
8.4. Руководство системного администратора
Руководство системного администратора – вспомогательный документ для прикладных программных продуктов и основной для серверных и системных, не имеющих непосредственных пользователей.
В случае небольших «монолитных» программ руководство системного администратора может оказаться документом небольшим

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

59
 порядок решения всевозможных вспомогательных задач;
 аварийные ситуации и способы их устранения.
Кроме того, в руководстве системного администратора могут быть описаны:
 пользовательский интерфейс административной консоли;
 утилиты командной строки и синтаксис их запуска;
 конфигурационные файлы и правила их написания;
 язык для составления управляющих скриптов.
Все зависит от того, какие средства для установки и настройки программы реализовали ее разработчики, какие именно инструменты есть у системного администратора.
Методика изложения материала в руководстве системного администратора сильно зависит от того, каким образом программой можно управлять. Если большинство задач решается через административную консоль с графическим интерфейсом, то документ будет больше похож на руководство пользователя или руководство администратора. Если системному администратору придется составлять конфигурационные файлы и писать скрипты, документ будет ближе к руководству программиста.
Приблизительная структура руководства системного администратора следующая:
1. Общие сведения о программе (комплексе)
2. Архитектура и принципы функционирования
3. Системные требования
4. Установка программы (комплекса)
5. Административная консоль и работа с ней

60
6. Файл конфигурации. Составление и правка
7. Обязательная
начальная
настройка
программы
(комплекса)
8. Проверка правильности функционирования программы
(комплекса)
9. Мероприятия по текущему обслуживанию программы
(комплекса)
10. Оптимизация работы программы (комплекса)
11. Аварийные ситуации и способы их устранения
Объем и особенности изложения информации в руководстве системного администратора зависят от используемых технических средств (ПК, серверных комплексов, планшетов, периферийных устройств и т. д.), применяемого программного обеспечения и решаемых с его помощью конкретных задач.
8.5. Руководство программиста
Программист – это специалист, который занимается разработкой алгоритмов и компьютерных программ на основе специальных математических моделей. Прикладные программисты занимаются в основном разработкой программного обеспечения прикладного характера, а также в их обязанности входит адаптация уже существующих программ под нужды отдельно взятой организации или пользователя.
Нормативной базой для составления данного документа может являться ГОСТ 19.504-79 «ЕСПД. Руководство программиста.
Требования к содержанию и оформлению», в котором выделяются следующие разделы:

61
 назначение и условия применения программы (назначение и функции, выполняемые программой, объем оперативной памяти, требования к составу и параметрам периферийных устройств, требования к программному обеспечению и т. п.);
 характеристики программы (временные характеристики, режим работы, средства контроля правильности выполнения и самовосстанавливаемости программы и т. п.);
 обращение к программе (описание процедур вызова программы, способы передачи управления и параметров данных и др.);
 входные и выходные данные (описание организации используемой входной и выходной информации и, при необходимости, ее кодирования);
 сообщения (тексты сообщений, выдаваемых программисту или оператору в ходе выполнения программы, описание их содержания и действия, которые необходимо предпринять по этим сообщениям).
В зависимости от особенностей документа допускается объединять отдельные разделы или вводить новые. В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т. п.).
8.6. Руководство системного программиста
Системный программист – это разработчик операционных систем, программных комплексов, обеспечивающих слаженную работу компонентов компьютера, который практически не занимается прикладными программами. Системный программист выстраивает многоуровневую структуру, которая объединяет отдельные компоненты
(работу процессора, сетевого оборудования,

62 оперативную память, выполнение прикладных программ и пр.) в модули, а модули – в компьютерную сеть.
Нормативной базой для составления данного документа может являться ГОСТ 19.503-79 «ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению», в котором выделяются следующие разделы:
 общие сведения о программе (назначение и функции программы и сведения о технических и программных средствах, обеспечивающих выполнение данной программы);
 структура программы (сведения о структуре программы, ее составных частях, о связях между составными частями и о связях с другими программами);
 настройка программы (описание действий по настройке программы на состав технических средств, выбор функций и др.);
 проверка программы
(описание способов проверки, позволяющих дать общее заключение о работоспособности программы: контрольные примеры, методы прогона, результаты);
 дополнительные возможности (описание дополнительных разделов функциональных возможностей программы и способов их выбора);
 сообщения системному программисту (тексты сообщений, выдаваемых в ходе выполнения настройки, проверки программы, а также в ходе выполнения программы, описание их содержания и действий, которые необходимо предпринять по этим сообщениям).

63
В зависимости от особенностей документа допускается объединять отдельные разделы или вводить новые. В приложении к руководству системного программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т. п.).
Вопросы для самоконтроля:
1. Для чего необходимо руководство пользователя?
2. Чем руководство оператора отличается от руководства пользователя?
3. Что включает в себя руководство программиста?

Источник

Понравилась статья? Поделить с друзьями:
  • Ибупрофен детский сироп инструкция по применению с какого возраста можно
  • Руководство для фрекен бок курпатова
  • Фронтлайн комбо спрей инструкция по применению
  • Нефромон плюс инструкция по применению цена отзывы врачей
  • Доклад на тему руководство в организации