Начало работы с документацией

Мы не делали никакой документации на моем рабочем месте. Я совершенно новичок в этом вопросе и прошу несколько советов по началу работы.

У меня есть несколько вопросов:

• Каковы основные документы, которые системный администратор должен написать и поддерживать? И почему это так важно?

• Как вы синхронизируете свою документацию с системой? Как вы минимизируете дублирование информации?

• Рекомендуемые руководства, лучшие практики, анти-шаблоны?

с 2003 года я документирую все в нашей внутренней вики.

Серверы

• спецификации оборудования
• информация о гарантии
• информация о сети
• и конечно же установленное программное обеспечение и конфигурация

Workflows

например, как добавить или удалить пользователя и предоставить ему / ей доступ ко всем соответствующим услугам

Важные ссылки

• ссылка на все ваши веб-интерфейсы
• ссылка на URL мониторинга (nagios, munin, apc-мониторинг ...)
• ссылка на вики (для печатной версии!)

Чрезвычайные инструкции

что делать, если сервер интрасети / интернет / веб-сервер / и т.д. не работает

Важный:

Выберите движок вики с легким экспортом в PDF!
Это не полезно, если вы находитесь в отпуске, сервер, на котором работает ваша вики, не работает, и никто не знает, что делать, потому что ваша документация отключена

Посмотрите на твики, documentwiki или mediawiki.

КСТАТИ:

есть плагин OpenOffice.org для прямой записи в mediawiki - очень удобно.

РЕДАКТИРОВАТЬ:

Также приятно записать некоторую информацию /home/adminuser/maintenance. Это делается быстро и может быть очень полезно, если на сервере работают несколько администраторов. например:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

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

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

Имея это в виду, некоторые предложения ...

• Избегайте больших блоков текста
• Списки маркеров - ваш друг
• Четкая схема золотая
• Повторение хорошая идея (1)
• Сделать это легко обновлять и расширять

(1) Не создавайте один источник правды и не заставляйте людей выслеживать его. Чем важнее идея, тем больше вы должны ее повторить.

Основные документы:

• Документация по серверу - спецификации / макеты дисков / установленное программное обеспечение / что-либо заметное
• Обычные процедуры - все, что не является «тривиальным», должно иметь документированную процедуру, особенно если это не было сделано ранее.

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

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

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

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

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

Не прямой ответ на ваш вопрос, а указатель в правильном направлении:

Я нашел Практику системного и сетевого администрирования Лимончелли и Хогана (она же Библия сисадминов) весьма ценной, потому что она касается вопросов «наилучшей практики», таких как документация. Если вы еще не знаете об этом, убедитесь, что вы расследуете это всякий раз, когда у вас есть возможность.

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

• Расположенный в центре.

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

• Простое редактирование и форматирование.

  Так много времени тратится на красивые шаблоны Word и соответствует стилю последнего автора. Если вы не утомляете людей этим, легче редактировать на ходу, и участники более склонны делать это. Разделяйте предметы по своему желанию с помощью TracLinks.

• История аудита.

  Важно знать, кто что изменил, когда и почему. Если вы можете связать его с запросами на изменение и журналами фиксации конфигурации, то даже лучше. Крюки SVN commit отлично подходят для этого.