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