Курс молодого бойца: Об оформлении программной документации (документация). Описание программы и описание применения Входные и выходные данные

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

Чтобы эта награда происходила чаще, требуется немалая фантазия в плане описания ресурса, и главная задача описания - привлечь пользователя , выделяя данное описание из тысячи подобных.

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

Но, если разобраться, то окажется, что тизер не содержит русского перевода, описание переведено Google-переводчиком из базы IMDB, а технические данные вообще скопированы с чужих сайтов. Да и много ли интереса проявит зритель, глядя на описание в 1-2 строчки? Тут требуется более основательная работа.

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

Сказать, что программа имеет версию «1.5.6» - не сказать ничего, потому что пользователь, заинтересовавшись, обязательно пройдет в Википедию или официальный сайт, чтобы найти дату выпуска этой самой версии. Если она окажется свежее, то он скачает ее именно с официального ресурса или торрента.

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

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

Чем больше вариантов описания вы предусмотрите, тем больше внимания привлечете к своему ресурсу, а это как раз то, что требовалось.

Предыдущие публикации:

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

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

В зависимости от особенностей программы допускается вводить новые разделы или объединять отдельные разделы. При описании программного продукта, содержащего несколько программных единиц (программ, подпрограмм), описание по указанной схеме дают для каждой программной единицы, придерживаясь при этом иерархии компоновки общего программного продукта. Так, например, если общая программа Control включает обращение к функции FileExist и процедуре Brackets, которая в свою очередь обращается к процедуре Error, и общая схема иерархии данного программного продукта изображена на рисунке 6, то описание необходимо начинать с программной единицы Control далее описывать программные единицы FileExist, Brackets, Stack, затем описать программную единицу Error в составе Brackets

Пример иерархии сложного программного продукта приведен на рисунке 6.

Программа контроля

расстановки скобок

в программах

Brackets FileExist Stack

Процедура проверки Функция проверки Модуль

правильности существования для работы

расстановки скобок файла со стеком

Процедура InitStack EmptyStack InStack OutStack

Расшифровки Процедура Функция Процедура Процедура

ошибок инициализации проверки включения извлечения

стека пустоты стека элемента элемента

в стек из стека

Рисунок 6 – Структурная диаграмма программы

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

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

В разделе "Описание логической структуры" приводится структурная диаграмма программы, в которой указываются имена и назначение составляющих модулей и подпрограмм (рисунок 6). Словесное описание структурных единиц программы сопровождается представлением укрупненных схем алгоритмов, в целом, не более трех листов. На первом листе приводится укрупненная схема алгоритма функционирования главной программы. Кроме этого, представляются схемы алгоритмов тех подпрограмм, которые отображают суть метода решения задачи. Примеры схем алгоритмов приведены на рисунках 7, 8, 9, 10.

Оформление схем алгоритмов должно соответствовать требованиям ГОСТ 19.701-90 "Схемы алгоритмов, программ, данных и систем". Первым блоком в любой схеме является блок ПУСК (или НАЧАЛО):

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

и межстраничные соединители

12 [ с листа...

12 [ на лист…

Стрелка, направленная к соединителю, означает, что управление передается блоку, номер которого указан внутри соединителя. Стрелка, направленная от соединителя, означает, что управление передается от блока, номер которого указан внутри соединителя. Каждая схема алгоритма для отдельной программной единицы изображается на отдельном рисунке. Рисунки нумеруются подряд внутри одного документа. Каждый рисунок имеет название, которое пишется над рисунком, и номер, который пишется под рисунком. Названием рисунка с изображением схемы алгоритма может служить наименование соответствующей программной единицы, например: "Схема алгоритма программы контроля" или "Схема алгоритма подпрограммы Error". Примеры схем алгоритмов приведены на рисунках 7, 8, 9, 10.

Рисунок 8 - Функция FileExist Рисунок 9 - Процедура Error

Рисунок 10 – Схема алгоритма процедуры Brackets

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

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

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

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

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

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

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

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

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

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

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

ГОСТ 19.402-78

Группа Т55

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

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

ОПИСАНИЕ ПРОГРАММЫ

Unified system for program documentation. Program description.

МКС 35.080

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

Постановлением Государственного комитета CCCР по стандартам от 18 декабря 1978 г. N 3350 дата введения установлена 01.01.80

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

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

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

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

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

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

3. Описание программы должно содержать следующие разделы:

общие сведения;

функциональное назначение;

описание логической структуры;

используемые технические средства;

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

выходные данные.

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

4. В разделе "Общие сведения" должны быть указаны:

обозначение и наименование программы;

программное обеспечение, необходимое для функционирования программы;

языки программирования, на которых написана программа.

5. В разделе "Функциональное назначение" должны быть указаны классы решаемых задач и (или) назначение программы и сведения о функциональных ограничениях на применение.

6. В разделе "Описание логической структуры" должны быть указаны:

алгоритм программы;

используемые методы;

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

связи программы с другими программами.

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

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

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

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

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

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

9. В разделе "Входные данные" должны быть указаны:

характер, организация и предварительная подготовка входных данных;

формат, описание и способ кодирования входных данных.

10. В разделе "Выходные данные" должны быть указаны:

характер и организация выходных данных;

формат, описание и способ кодирования выходных данных.

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

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

7-12. (Введены дополнительно, Изм. N 1).



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

Текст программы

Пример.

Спецификация программы

В разделе спецификация приводится точное название программы и ее состав. Форма спецификации приведена в приложении 2. Графы спецификации заполняют следующим образом:

1. в графе "Обозначение" указывают обозначение основных программных
компонентов;

2. в графе "Наименование" указывают полное наименование соответствующего компонента;

3. в графе "Примечание" - дополнительные сведения, относящиеся к записанным в спецификации программам.

Исполняемый файл программы "Игра "Лабиринт"" имеет название Labirint.exe и расположен на диске F в каталоге Student\Kursov\Labirint. Состав проекта:

Наименование	Обозначение	Примечание
Acl	Файл плана помещений	Создается в приложении
Helpi	Файл помощи	Создается в приложении
Labirint.Dof	Файл параметров проекта	Содержит, текущие установки проекта: настройки компилятора и компоновщика, имена служеб­ных каталогов, условные дирек­тивы
Labirint.Dpr	Файл проекта	Связывает все файлы, из которых состоит приложение
Labirint.Dsk	Файл, содержащий Desktop-настройки проекта	Содержит информацию о том, какие окна открыты и в каких позициях они расположены
Labirint.Res	Файл ресурсов	Содержит пиктограммы, графи­ческие изображения
Unit 1. Pas	Файл программного моду­ля для формы №1	Определяет функциональность формы №1.
Unit2.Pas	Файл программного моду­ля для формы №2	Определяет функциональность формы №2.
U»it3.Pas	Файл программного моду­ля для формы №3	Определяет функциональность формы №3.
Unitl.Dfm	Файл формы №1	Содержит список свойств всех компонентов, включенных в форму №1.
Unit2.Dfm	Файл формы №2	Содержит список свойств всех компонентов, включенных в форму №2.
Unit3.Dfm	Файл формы №3	Содержит список свойств всех компонентов, включенных в форму №3.
Uuitl.Dcu	Объектный файл для Unit1. Pas	Откомпилированная версия Unit1.Pas.
Uuit2.Dcu	Объектный файл для Unit2.Pas	Откомпилированная версия Unit2.Pas.
Unit3.Dcu	Объектный файл для Unit3.Pas	Откомпилированная версия UnM.Pas.

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

Раздел "Описание программы" согласно ГОСТ 19.402-78 должен содержать следующие подразделы:

· общие сведения;

· функциональное назначение;

· описание логической структуры;

· используемые технические средства;

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

· выходные данные.

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

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

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

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

В подразделе "Используемые технические средства" должны быть указаны типы ЭВМ и устройств, которые используются при работе программы.

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

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

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