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

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

Серверы

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

Рабочие процессы

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

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

• свяжитесь со всеми своими веб-интерфейсами
• свяжитесь с контролирующими URL (nagios, munin, apc-контролируя...)
• свяжитесь с Wiki (для печатной версии!)

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

что сделать, если сервер/и т.д. сервера/Интернета/сети интранет снижается

Важный:

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

Взгляните на twiki, docuwiki или mediawiki.

BTW:

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

Править:

Его также хороший записать некоторый infos к /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) Не создавайте один источник истины и вынуждайте людей выследить его. Чем более важный идея, тем больше необходимо повторить его.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Контрольная история.

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