Руководство администратора: структура и что в нем описать

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

Руководство администратора: структура и что в нем описать
Содержание
  1. Для чего нужно руководство администратора
  2. Чем руководство администратора отличается от руководства пользователя
  3. Что говорят стандарты
  4. Структура руководства администратора
  5. Установка и настройка
  6. Управление пользователями и правами
  7. Резервное копирование и восстановление
  8. Мониторинг, обновления и нештатные ситуации
  9. Типичные ошибки
  10. Частые вопросы

Для чего нужно руководство администратора

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

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

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

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

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

ПризнакРуководство пользователяРуководство администратора
ЧитательСотрудник, работающий в системеСпециалист по сопровождению и инфраструктуре
Главный вопросКак выполнить рабочую операциюКак установить, настроить и поддерживать систему
СодержимоеЭкраны, кнопки, сценарии, сообщения об ошибкахУстановка, роли, резервное копирование, журналы, обновления
Технический уровеньБазовые навыки работы с компьютеромЗнание операционных систем, сетей, баз данных
Как часто открываютЕжедневно, пока не освоятПри установке, обновлении и сбоях

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

Что говорят стандарты

Самого названия "руководство администратора" в старых стандартах нет, и это нормально. В Единой системе программной документации ближайший по смыслу документ - руководство системного программиста. Его содержание задает ГОСТ 19.503-79: общие сведения о программе, структура, настройка, проверка, дополнительные возможности и сообщения системному программисту.

В комплексе ГОСТ 34 соответствующие задачи решают инструкция по эксплуатации комплекса технических средств и технологическая инструкция, а перечень всех документов задан в ГОСТ 34.201-89. Заготовки лежат на сайте: шаблон инструкции по эксплуатации КТС и шаблон технологической инструкции, шаблон по ГОСТ 19 - шаблон руководства системного программиста.

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

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

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

Разделы руководства администратора повторяют этапы жизни системы от подготовки до восстановления.
Разделы руководства администратора повторяют этапы жизни системы от подготовки до восстановления.
РазделЧто описать
Общие сведенияНазначение документа, архитектура системы, состав компонентов, версия, список связанных документов
Требования к окружениюСерверы, операционные системы, СУБД, сетевые порты, внешние сервисы, требования к ресурсам
УстановкаПорядок развертывания, исходные файлы, команды, проверка результата
НастройкаКонфигурационные файлы, параметры, интеграции, почта, каталог пользователей
Управление доступомРоли, права, создание и блокировка учетных записей
Резервное копированиеЧто копируется, расписание, место хранения, проверка копий, восстановление
Мониторинг и журналыГде лежат журналы, что проверять, какие события считать тревожными
ОбновлениеПорядок установки новых версий и откат
Нештатные ситуацииСимптомы, причины, действия, куда обращаться

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

Установка и настройка

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

  1. Подготовьте сервер: операционная система, пакеты, учетная запись для запуска сервиса, открытые порты.
  2. Установите и настройте СУБД, создайте базу и пользователя с минимально необходимыми правами.
  3. Разверните приложение из дистрибутива и распакуйте его в указанный каталог.
  4. Заполните файл настроек: адрес базы данных, параметры почты, адрес сервиса авторизации.
  5. Запустите службы и проверьте, что система отвечает на контрольный адрес.
  6. Выполните контрольный сценарий: войдите под тестовой учетной записью и создайте пробную запись.

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

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

Управление пользователями и правами

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

Лучше всего матрицу ролей показать таблицей: по строкам операции, по столбцам роли. Так администратор сразу видит, что можно сотруднику, а что только руководителю.

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

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

Резервное копирование и восстановление

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

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

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

Мониторинг, обновления и нештатные ситуации

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

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

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

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

Типичные ошибки

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

  • В документе нет ни одной точной команды, только общие слова вроде "настроить сервер".
  • Описана установка, но нет раздела об обновлении и откате.
  • Резервное копирование есть, а инструкции по восстановлению нет.
  • В тексте вписаны реальные пароли, адреса внутренних серверов и ключи.
  • Документ не соответствует текущей версии системы, и ни в одном месте не указано, к какой версии он относится.
  • Руководство администратора и руководство пользователя склеены в один файл.

Если систему передают по ГОСТ, укажите документ в ведомости эксплуатационных документов (шаблон ведомости эксплуатационных документов по ГОСТ 34). Сведения об экземплярах и комплектности вносят в формуляр, о нем подробно в материале паспорт и формуляр системы.

Частые вопросы

Нужно ли руководство администратора, если система простая?

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

Руководство администратора и руководство системного программиста - это одно и то же?

По смыслу они близки. Руководство системного программиста описано в ГОСТ 19.503-79 и относится к программам. Название руководство администратора принято в практике автоматизированных систем и корпоративных сервисов, содержание часто совпадает.

Можно ли включать в документ пароли и учетные данные?

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

Кто пишет руководство администратора?

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

Как проверить, что руководство администратора написано хорошо?

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

Читайте также