На моем рабочем месте мы не занимались никакой документацией. Я совершенно новичок в этом и прошу совета, чтобы начать работу.
У меня есть несколько вопросов:
Какие основные документы должен писать и поддерживать системный администратор? И почему это так важно?
Как вы синхронизируете свою документацию с системой? Как минимизировать дублирование информации?
Рекомендуемые гайды, лучшие практики, антипаттерны?
с 2003 я документирую все в нашей собственной вики.
например как добавить или удалить пользователя и предоставить ему / ей доступ ко всем соответствующим услугам
что делать, если сервер интрасети / Интернет / веб-сервер и т. д. не работает
Выберите движок вики с легким экспортом в PDF!
Это бесполезно, если вы в отпуске, сервер, на котором работает ваша вики, не работает, и никто не знает, что делать, потому что ваша документация отключена.
Взгляните на твики, документацию или медиавики.
Eсть Плагин 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) Не создавайте один источник истины и заставляет людей выслеживать его. Чем важнее идея, тем чаще ее следует повторять.
Основные документы:
Синхронизация документации может быть в значительной степени делом «исправляй, если видишь ошибки». Наряду с этим необходимо осознать, что документация может и будет устаревшей, и что ей не следует слепо следовать, не принимая это во внимание. Документация предназначена для помощи администратору в решении задач, а не является пошаговым набором правил, заменяющим критическое мышление.
Сведение к минимуму дублирования - в этом может помочь что-то вроде вики, где вы можете связать документацию вместе, вместо того, чтобы повторять информацию, вы просто даете ссылку на нее. Проблема в том, что человек, пишущий документацию, должен знать, что информация, которую он собирается скопировать, уже существует. Обычно это вопрос хорошей организации.
Я обнаружил, что создание шаблона очень помогает. В моем случае это шаблон Word, но используйте все, что вам подходит. Создайте файл-скелет с полем оглавления и разделами по желанию. После того, как вы воспользуетесь им пару раз и произведете точную настройку, вы сможете создавать новые документы намного быстрее. Единообразие формата будет большим подспорьем как при создании документа, так и при его дальнейшем использовании. Документацию необходимо хранить в логическом месте и в логической структуре каталогов.
Лично я против повторения по той простой причине, что это делает обслуживание излишне трудным и требует много времени. Вместо того, чтобы дублировать документы или части документов, при необходимости создавайте ссылки на другие документы. Если что-то изменится, вам никогда не придется изменять соответствующую документацию более одного раза или более чем в одном месте, иначе вы воля иметь коллекцию противоречивых документов, которая никому не помогает.
Создавая документацию, помните, для чего она нужна. Кому-нибудь позже понадобится его использовать. Можно ли будет выполнять эту работу без предварительного знания?
Не прямой ответ на ваш вопрос, а указатель в правильном направлении:
я нашел Практика системного и сетевого администрирования, от Лимончелли и Хогана (также известная как Библия системного администратора), является весьма ценным, потому что он касается вопросов «передовой практики», таких как документация. Если вы еще не знаете об этом, обязательно исследуйте его при первой возможности.
Для меня самое важное - сделать его простым в использовании. Если сложно организовать, люди будут избегать этого. я выбираю Tracwiki в качестве носителя для нашей документации по следующим причинам:
Расположенный в центре.
Наличие более одной активной копии любого документа приводит к путанице. Если вы можете направить всех в одно и то же место, как участников, так и аудиторию, вы можете упростить процесс.
Простое редактирование и форматирование.
Столько времени тратится на красивые шаблоны Word, соответствующие стилю последнего автора. Если вы не утомляете людей этим, то легче редактировать на ходу, и участники будут более склонны делать это. С TracLinks разделяйте элементы на столько, сколько хотите.
История аудита.
Важно знать, кто какие изменения внес, когда и почему. Еще лучше, если вы можете привязать его к билетам запроса на изменение и журналам фиксации конфигурации. Перехватчики фиксации SVN отлично подходят для этого.