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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Наименование документа	Наименование стандарта	Стоимость разработки
Руководство программиста на ПО	ГОСТ 19.504	100 тыс. р.

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

Возможно, вас также заинтересует:

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

---

643.02069436.41NNN-01
33 01-1

«Шифрование
данных»

Программа

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

643.02069436.41NNN—01
33 01-1

Листов 6

---

АННОТАЦИЯ

Приводится руководство
программиста программы «Шифрование
данных».

Программа предназначена
для шифрования и дешифрования данных,
с применением алгоритма шифрования
«Шифр-Гост 28147-89».

Ограничения программы: программа
аварийно завершается при загрузке
файлов с размером более 500 МБ.

Условия эксплуатации программы:

возможность применения в локальной
сети;

на персональных компьютерах
с процессором не ниже 300МГц, минимум
оперативной памяти 16 MБ и операционная
система не ниже Windows 95.

Распространяется на дискетах.

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

---

СОДЕРЖАНИЕ

стр.

---

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

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

Описываемая программа предназначена
для шифрования и дешифрования
данных, хранящихся в файлах.

1.2 Функции программы

• Функция
  открытия и чтения файла “LoadFile”
  вызывается путем нажатия
  Файл->Открыть и
  загрузка данных из файла при выборе
  файла в диалоговом окне.

• При нажатии Шифрование->Зашифровать
  программа вызывает процедуру “Coding”,
  которая зашифровывает данные и выводит
  результат в окно для ввода текста.

• При выборе в меню
  Шифрование->Расшифровать
  – программа вызывает процедуру
  “Recoding”,
  которая расшифровывает данные с выводом
  в результата в текстовое окно.

• Запись данных в файл
  происходит путем нажатия Файл->Сохранить
  — вызове функции
  “SaveFile”и
  выборе в диалоговом окне документа для
  записи данных.

1.3 Использование оперативной памяти

Количество необходимой оперативной
памяти определяется размером обрабатываемых
данных, плюс к этому 1 МБ для загрузки
самой программы и создания всех
необходимых переменных и структур.

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

Операционная система Windows95
и выше.

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

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

2.2 Функционирование программы после
сбоев

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

3.1 Способы вызова программы с различных
носителей данных

Программа может вызываться с любых
носителей.

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

Исполняемым файлом программы является
файл «CodingGost.exe«.

3.3 Способы передачи управления и
параметров данных

Передача параметров производится в
режиме диалога программы с пользователем.

3.4 Обращение к программе – приложению

С помощью программ файл — менеджеров
зайти в каталог, в который установлена
программа и запустить файл «CodingGost.exe».

4.1 Формат, характер и организация входных
данных

Загрузка данных в виде текста или файла
любого формата для (рас)зашифровывания.

4.2 Формат, характер и организация выходных
данных

Cохранение (рас)зашифрованных
данных в файл любого формата, либо
простым отражением в текстовом поле.

5.1 Сообщения программисту и действия
по ним

№ п/п	Сообщение	Описание	Действия
1	2	3	4
1.	“Отсутствуют данные для обработки!”	Системное окно сообщения с информацией, о том, что файл не открыт.	Загрузить файл.
2.	“Не задан ключ!”	Системное окно сообщения с информацией, о том, что ключ не задан.	Ввести ключ для шифрования в соответствующее поле.

---

6.1 Примеры

Производится
открытие файлов путем
нажатия Файл->Открыть и
загрузка данных из файла при выборе
файла в диалоговом окне.

Возможен ввод текста для шифрования в
окно и его загрузка из него.

При нажатии Шифрование->Зашифровать
программа зашифровывает данные и выводит
результат в окно для ввода текста.

При выборе в меню Шифрование->Расшифровать
– происходит расшифровка данных с
выводом в результата в текстовое окно.

Запись данных в файл происходит путем
нажатия Файл->Сохранить и выборе
в диалоговом окне документа для записи
данных.

Можно изменить параметры шифрования –
ключ шифрования, “S
— блоки”.

6.2 Иллюстрации

Основная форма

Окно ввода
(отображения) Ключ Окно
вывода (отображения)

Главное меню
Строка состояния
процесса

---

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

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

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

АННОТАЦИЯ

В данном руководстве содержится информация, описывающая прикладное программное обеспечение для участка сборки и настройки ДВДТ – участок ДВДТ (далее по тексту – участок). Документ содержит информацию о доступе к функциям системы управления 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. ЕСПД. Схемы алгоритмов, программ, данных и систем. Обозначения условные и правила выполнения

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

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

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

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

Когда требуется руководство программиста?

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

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

Структура документа

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

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

Оформите заявку и задавайте все интересующие вас вопросы по телефону
+7(499)755-74-33 e-mail Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра. или через форму заказа.

О нормах и законах или Как вылечить процесс техдокументирования (спойлер: это больно)

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

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

______________________________

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. Файл Readme.

3. Changelog.

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

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

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

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

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

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

Формировать перечень документов можно по простейшему алгоритму – смотрите Рис.  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 и технологических норм, но это уже совсем другая история…

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

Cтраница 1

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

Руководство программиста — документ, содержащий сведения, необходимые для полного использования возможностей программы.
 [2]

Руководство программиста 13 175 — 83 Автоматизированные системы управления.
 [3]

В Руководство программиста для программы-компонента включаются сведения о способах приема и передачи параметров, обращения к программе, используемой базе данных, версии операционной системы, программах ОПО АСУТП и вычислительных ресурсах.
 [4]

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

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

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

В программную документацию рабочего проекта входят: руководство программиста; руководство оператора; эксплуатационная программа или текст программы; описание контрольного примера.
 [8]

Знакомство со стандартными языками позволяет им под руководством программиста, объединившись в творческие бригады, уже в 4 — 5 — м классе участвовать в разработке общественно-полезных программ. Так, например, было создано программное обеспечение подготовки перфолент для программно-управляемых вышивальных аппаратов, информационно-справочная система по белковым соединениям и другая — для книгообмена.
 [9]

Особо подчеркнем, что прежде чем пользоваться директивами, необходимо тщательно ознакомиться с соответствующим руководством программиста.
 [10]

Исходя из этого, удобно разделить всю документацию по программе на описание применения, руководство оператора, руководство программиста и руководство системного программиста.
 [11]

Все граничные значения параметров, используемых в программа, методы подготовки программ и режимы работы машины описаны в Руководстве программиста для каждого конкретного типа ЭВМ.
 [12]

Специфика такой работы, форматы сообщений в каналах связи, схемы подключения машин и требования к программам подробно рассматриваются в Руководстве программиста для каждого типа ЭВМ.
 [13]

При проектировании пакета прикладных программ должны быть построены документы: 1) пояснительная записка; 2) общее описание; 3) руководство программиста; 4) описание языка; 5) описание программ; 6) порядок и методика испытаний.
 [14]

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

Страницы:  

   1

   2