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

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

Требования
к оформлению руководства системного
программиста излагаются в ГОСТ 19.503-79
«Руководство системного программиста.
Требования к содержанию и оформлению».

5.1 Гост 19.503-79

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

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

5.1.1 Общие положения

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

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

– общие
сведения о программе;

– структура
программы;

– настройка
программы;

– проверка
программы;

– дополнительные
возможности;

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

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

5.1.2 Содержание разделов

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

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

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

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

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

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

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

5.2 Пример

5.2.1 Общие сведения о программе

Программа
«Автоматизированное рабочее место
читателя» предназначена для обеспечения
простого и удобного доступа удаленных
пользователей к ресурсам различных
информационных служб. Удаленными
пользователями могут являться любые
пользователи HTTP-сервера, на базе
которого функционирует программа.
Ресурсами информационных служб могут
являться различные удаленные базы
данных (библиографические, полнотекстовые,
базы данных запросов на доставку
документов, тезаурусы), доступные по
протоколу ISO 23950. Таким образом, программа
является промежуточным звеном многозвенной
информационной системы, обеспечивающим
пользователей следующими возможностями:

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

• заказ
  документа (копии) по найденному
  библиографическому описанию;

• проверка
  статуса заказа;

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

Другими
словами, программа является Z39.50-клиентом
с Web-интерфейсом пользователя. Поэтому
для работы с программой пользователю
необходимы
лишь Web-агент (Netscape
Navigator,
MS
Internet
Explorer,
Lynx
и т.п.) и надежная связь с HTTP-сервером,
на котором выполняется программа.

Программа
может функционировать на любых технических
средствах под управлением любой
операционной системы, отвечающей
стандарту ISO/IEC
9945-1 (POSIX)
и спецификациям X/Open
CAE
specifications,
Issue
4, July
1992 (XPG4).
Обязательными требованиями для выполнения
программы являются поддержка стека
протоколов TCP/IP и наличие HTTP-сервера,
поддерживающего CGI.

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

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

Документ оформляется в соответствии с правилами предусмотренными ГОСТ 19.105, ГОСТ 19.106 и другими стандартами Единой системы программной документации (ЕСПД).

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

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

Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента 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.

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

---

Итог

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---