Мне поручили настроить и управлять совершенно новой лабораторной средой, состоящей из множества машин с разными ролями. Есть хост виртуальной машины, несколько веб-серверов, несколько серверов баз данных и т. д.
Существуют очень специфические потребности и процессы, которые необходимо задокументировать в рамках этой лабораторной среды. Например, мы не хотим, чтобы были включены автоматические обновления Windows, и нам нужно зафиксировать множество мыслей, которые можно будет объяснить разным сторонам (руководителям, менеджерам, разработчикам, ИТ-менеджерам, специалистам по контролю качества).
Так что, пока я делаю настройку, я действительно хочу зафиксировать эти разговоры в каком-то формальном документе. Я просто собирался пойти дальше и создать Word .doc, организовав каждую роль сервера с несколькими дискретными разделами:
- Управляющее резюме
- Потребности в техническом обслуживании
- Инвентаризация установленного программного обеспечения
- Доступное оборудование
- Аппаратные настройки по умолчанию
Я хотел бы узнать, есть ли лучшие шаблоны, которым я могу следовать при создании документации для этих машин. Я надеюсь, что все, что я в итоге создам, будет достаточно хорошим, чтобы кто-то другой переделал машины, если это потребуется.
решение1
Наиболее важными вещами для хорошей системы документирования являются:
- Легко обновлять (или люди не будут обновлять его, что сделает его более чем бесполезным)
- Удобный доступ — из любого места, с нескольких устройств.
- Хорошая организация — людям легко найти нужную информацию, дублирование одной и той же информации минимально.
Я пробовал документы Word. Они не справляются ни с одним из трех пунктов. Документы Word трудно обновлять, в итоге у людей разные копии и т. д.
Лучшая система, которую я нашел для своего использования, — это вики. DokuWiki вполне подходит для моих целей. Я могу легко получить к ней доступ и обновлять ее из любой точки мира.
У меня есть моя вики, которая содержит страницы, описывающие всю настройку сети, которые ссылаются на страницы для каждого сервера, кластера и приложения. Таким образом, все подробности о конкретном элементе хранятся на отдельных страницах и могут быть связаны с любым местом, где это уместно - когда что-то меняется, мне нужно изменить это только на одной странице, и я могу легко найти нужную информацию.
Он также позволяет указывать шаблоны пространств имен, поэтому, когда я создаю новую страницу сервера, она предварительно заполняется таблицами для ввода IP-адресов, конфигурации оборудования и т. д. Во всех пустых полях написано FIXME, поэтому я могу выполнить поиск FIXME по всей вики и посмотреть, чего не хватает в документации.
Если вы действительно хотите пофантазировать, вы можете написать плагины, которые берут такие вещи, как файлы конфигурации, анализируют их и отображают в удобном для чтения формате. Например, я написал плагин PatchPanel, который берет текстовое описание сетевой коммутационной панели и рисует ее изображение с метками того, куда идет каждый порт.
http://blog.emsley.ca/2014/04/documentation.htmlесть более полное описание того, как я это настроил (отказ от ответственности: ссылка на мой блог, хотя полностью по теме).