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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

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

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

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

АННОТАЦИЯ

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

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

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

Составляем документацию разработчика пошагово без диет и тренировок

Недостаточно просто написать инструкции — важно, как, в каком порядке и где вы их разместите. 

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

• инфраструктурой as a service;

• фреймворками и библиотеками на Go, C#, TypeScript;

• трейсингом, мониторингом, логированием, нагрузочным тестированием;

• инструментами для работы с базами данных и аналитикой;

• виртуализацией и контейнеризацией.

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

Дисклеймер: в этой статье упор сделан на содержание, структуру и формат. Сугубо гуманитарные вещи вроде орфографии и пунктуации обсуждать не будем — они на вашей совести.

Зачем вам документация

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

Плюсы хорошей документации:

• увеличивается bus-фактор: знание распространяется между большим числом людей, и его сложнее потерять;

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

• коллеги быстро находят ответы (в том числе через Ctrl+F), решают проблемы и разбираются в технологии: как следствие, увеличиваются их продуктивность и доход компании;

• для внешней документации: разгружает сотрудников техподдержки.

Хорошая ли у вас документация?

Пройдите маленький тест и посчитайте набранные баллы:

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

Не торопитесь переходить к действиям — сначала налейте чай и просто прочитайте статью.

Шаг 1. Соберите всю информацию

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

• старая документация;

• личные страницы — ваши и коллег (например, в Confluence);

• ответы в чатах;

• репозитории (например, в GitLab);

• Word и другие текстовые редакторы;

• ссылки в закладках браузера.

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

• легче обновить одну, чем две;

• одну из версий точно забудут обновить — и она будет вводить в заблуждение; как назло всегда будут находить именно её.

Шаг 2. Выбросите мусор

Одна актуальная статья лучше десяти устаревших.

Проверено: если у вас в документации найдут устаревшие сведения, никто не будет читать дальше — спросят у вас лично.

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

Под «избавлением» имеется в виду одно из двух:

• добавление в архив — предпочтительно;

• безвозвратное удаление.

Если после этого вообще ничего не осталось, это нормально.

Если вы детально не знаете начинку описываемой технологии

После такой «чистки» обычно очень легко дышится — будто камень с шеи снял.

Шаг 3. Найдите частые вопросы и сценарии

Наша новая задача — определить, что нужно задокументировать или актуализировать в первую очередь. Обычно это выясняется так:

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

2. Читаете комментарии с вопросами под инструкциями, если есть.

3. Опрашиваете аудиторию. Обычно это либо пост в публичном чате, либо вопросы знакомому коллеге лично. Формы с опросами, как правило, неэффективны, поскольку собирают мало ответов.

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

Вначале выпишите вопросы и сценарии, а потом начинайте писать для них тексты.

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

Шаг 4. Поделите на разделы

Цель — наметить примерный план будущей базы знаний. Он может дополняться, когда появятся новые данные, но пока нужно сделать «скелет» для всего остального. 

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

Добавить их все сплошным списком вразнобой — провальный вариант. Ctrl+F тут тоже не всегда поможет, потому что, например, вы пишете в названии страницы «кубер», а ваш читатель ищет «Kubernetes» или «k8s», ничего не находит — и идёт к вам в личку.

Целевая аудитория

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

Подумайте, какие люди будут её читать. Например:

• только ваша команда;

• другие команды, им нужна одна функциональность;

• другие команды, им нужна разная функциональность;

• и ваша команда, и другие команды.

Внешние команды не должны видеть странички «Черновик to do», «[убрать в архив] 2 декабря». Держите их в отдельной папке для черновиков.

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

Шаг 5. Составьте словарь терминов

Одна сущность — один термин.

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

Термины должны легко находиться через Ctrl+F.

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

Шаг 6. Утвердите правила для команды

Заранее обговорите с командой правила и план ведения документации.

• нет структуры — статьи добавляют куда попало;

• никто не убирает устаревшую информацию;

• команда не всегда знает, что у неё есть в документации;

• много заброшенных статей;

• много пустых статей из 2016 с пометкой «to do»;

• перемешаны внутренние черновики и внешняя документация;

• нет архива;

• ведётся на русском, английском, латинском и древнегреческом.

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

Пример правил по созданию новых страниц:

Советую почитать о методике совместного ведения документации.

Шаг 7. Напишите тексты

Лучший способ научиться писать хорошие инструкции — это отдавать их на вычитку. Желательно — редактору. Если его нет — любому коллеге. Я не о проверке пунктуации, а о том, понятно ли написана статья, полная ли в ней информация.

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

• Освойте инструменты форматирования там, где вы ведёте документацию. Примеры: макросы Confluence, синтаксис Markdown и HTML.

  

• Укажите, для кого страница и что в ней описано, — тогда человек сразу поймёт, нужно ли ему это читать.

• Не пишите сплошные тексты — делите их на логические абзацы и разделы. При грамотной вёрстке легче сходу найти ответ.

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

• Оформите разводящую страницу. Это главная страница с основной информацией и разделами по темам. Она нужна, чтобы читатель быстро понял, где искать необходимую инструкцию.
  Пример Ozon Docs
  Пример Yandex Cloud
  Пример Amazon EC2

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

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

• Избегайте канцеляризмов — они утяжеляют тексты: «для того чтобы в данном процессе осуществить определённую функциональность».

• Выделяйте в тексте важное, но не превращайте его в одни сплошные плашки.

• Укажите контакты команды, чтобы читатели знали, к кому обращаться.

Шаг 8. Добавьте FAQ

FAQ — страница с часто задаваемыми вопросами и ответами на них. 

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

Используйте список из шага 3, если он есть.

FAQ — это не полноценная инструкция. Не дублируйте тексты и не делайте ответы очень подробными. 

Оптимальный вариант — краткий ответ со ссылкой на полную инструкцию. Например, «Да, это возможно. Подробнее в статье “Как создать N”».

Для продвинутых идеалистов:

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

Шаг 9. Продумайте, как вашу документацию будут находить

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

Подумайте, куда ваши коллеги чаще обращаются за помощью:

• к вам в личку: закрепите ссылку на документацию у себя в профиле на корпоративном портале;

• в ваш чат: закрепите ссылку в шапке, закреплённом сообщении, сделайте так, чтобы каждому вступившему ссылку отправлял бот;

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

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

Шаг 10. Проанализируйте результат

Лучший источник для анализа — ваша аудитория. 

Есть несколько способов понять, решает ли проблемы ваша документация.

Что обычно делаю я:

• Считаю количество запросов в чатах. 

• Провожу мини-исследование среди читателей: готовлю открытые вопросы, спрашиваю, долго ли они искали информацию, что именно они искали, нашли ли ответы на свои вопросы.

• Изучаю статистику просмотров в Confluence и Grafana: если за месяц никто не обратился к документации, нужна ли она?

Сама не практикую, но отличная идея:

• Добавить фичу «Оцените статью». Такие макросы точно есть в Confluence.

Если на этом этапе не всё гладко — это нормально, просто будьте готовы что-то дописать, поменять местонахождение статьи.

Итог

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

И помните, что документация — ваш общий продукт. 

Буду рада ответить на ваши вопросы. Делитесь мнением и историями в комментариях.

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

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. Граничные
значения.

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

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

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

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

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

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

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

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

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

ГОСТ 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. Структура и оформление документа устанавливаются в соответствии с ГОСТ 19.105-78.

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

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

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

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

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

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

сообщения.

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

 2. СОДЕРЖАНИЕ РАЗДЕЛОВ

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

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

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

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

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

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