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

21

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

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

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

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

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

chickeninabiscuit
источник

Ответы:

15

с 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.
ThorstenS
источник
2
+1 за запасной намек, если вики не работает.
Мануэль Фо
Что такое? Похоже, OpenOffice, но я не могу понять, последнее "о". Если бы вы могли назвать плагин, было бы здорово.
Даниэль С. Собрал
3
верно, OOo - это OpenOffice.org ;-) Расширение: extensions.services.openoffice.org/de/project/wikipublisher
ThorstenS
13

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

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

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

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

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

Беван
источник
2
Однако при наличии более одного источника документации у вас есть более одного места, которое требует обновления, если оно устарело и нуждается в замене. Хороший способ обойти это (если у вас есть вики или что-то подобное) - попытаться сделать один истинный источник правды и связать его с таким количеством мест, сколько необходимо.
Марк
В некоторой степени я согласен - ссылки и перекрестные ссылки действительно могут быть очень полезными. Хотя есть компромисс - при проектировании баз данных обычно используют ненормализованные таблицы для облегчения отчетности. Я думаю, что тот же подход уместен здесь - чтобы упростить потребление документации, повторяющиеся ключевые факты могут быть полезны.
Беван
Можно распространять принципы широко, но для таких вещей, как IP-адреса, пароли, управление конфигурацией, централизованный единый авторитетный источник данных с адекватными резервными копиями является ключом к разумному администрированию.
Том Х
Я бы согласился - если он хорошо известен и легко доступен - единственный авторитетный секретный источник - слишком распространенный антипаттерн.
Беван
Я категорически не согласен с повторением, потому что один будет обновляться, а другие нет. Или они будут непоследовательно обновлены. Вместо этого более важные документы должны быть более легко связаны .
gWaldo
5

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

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

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

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

отметка
источник
4

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

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

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

Джон Гарденье
источник
3

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

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

Тибериу ана
источник
Во втором издании этой книги есть глава по документации. В соответствующей книге «Управление временем для системных администраторов» есть глава, посвященная документации, которая больше сфокусирована на том, что вам нужно делать, а не на том, что ваша организация должна делать.
TomOnTime
0

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

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

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

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

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

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

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

Дэн Карли
источник
Я также использую trac для документации одного проекта. Чего действительно не хватает, так это своего рода крошки в вики. Я надеюсь, что это скоро.
ThorstenS