Початок роботи з документацією

Ми не робили жодної документації на моєму робочому місці. Я абсолютно нова в цьому і прошу поради, як розпочати.

У мене є кілька питань:

• Які основні документи, які повинен писати та підтримувати системний адміністратор? І чому вони такі важливі?

• Як ви зберігаєте свою документацію в синхронізації з системою? Як ви мінімізуєте дублювання інформації?

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

з 2003 р. я документую все в нашому вікі.

Сервери

• технічні характеристики
• інформація про гарантію
• мережева інформація
• і звичайно встановлене програмне забезпечення та конфігурація

Робочі процеси

наприклад, як додати або видалити користувача та надати йому доступ до всіх відповідних послуг

Важливі посилання

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

Інструкція з надзвичайних ситуацій

що робити, якщо інтранет-сервер / Інтернет / веб-сервер / тощо не працює

Важливо:

Виберіть движок wiki з простим експортом у PDF!
Це не корисно, якщо ви відпочиваєте, сервер, на якому працює ваша вікі, не працює, і ніхто не знає, що робити, оскільки ваша документація офлайн

Погляньте на twiki, docuwiki або 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.

Хоча ви усвідомлюєте, що хоча всі хочуть (і потребують) документацію, ви також повинні визнати, що ніхто не встигає прочитати та вивчити матеріали.

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

Зважаючи на це, деякі пропозиції ...

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

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

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

• Документація на сервер - специфікації / макети диска / встановлене програмне забезпечення / будь-що зауваження
• Загальні процедури - все, що робиться, що не є «банальним», має мати документально підтверджені процедури, особливо якщо це щось, що не робилося раніше.

Синхронізація документації може бути значною мірою "виправити це, коли ви бачите помилки". Поряд із цим потрібно усвідомити, що документація може бути і буде застарілою, і що її не слід сліпо слідувати, не враховуючи це. Документація існує для того, щоб допомогти адміністратору у виконанні завдань, а не бути поетапним набором правил, які замінюють критичну думку.

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

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

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

Створюючи свою документацію, майте на увазі, для чого вона потрібна. Хтось у більш пізній час повинен буде ним скористатися. Чи можна буде виконувати цю роботу без попереднього знання?

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

Я вважав, що Практика системного та мережевого адміністрування Лімончеллі та Хоган (він же Біблія Сисадміна) є досить цінною, оскільки йдеться про проблеми "найкращої практики", такі як документація. Якщо ви ще не знаєте про це, обов'язково досліджуйте це, коли ви отримаєте можливість.

Для мене найважливішим моментом є полегшення використання. Якщо важко оркеструвати, тоді люди будуть уникати цього. Я вибираю Trac вікі «сек в якості середовища для нашої документації з наступних причин:

• Розташований в центрі міста.

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

• Просте редагування та форматування.

  Стільки часу витрачається на гарні шаблони Word та відповідність стилю останнього автора. Якщо ви не обманюєте людей цим, тоді простіше редагувати в дорозі, і дописувачі схильні до цього. Виділіть деталі скільки завгодно за допомогою TracLinks.

• Історія аудиту.

  Важливо знати, хто що змінив, коли і чому. Якщо ви можете зв’язати це із запитом на зміну квитків та конфігурацію журналів, то ще краще. Для цього чудово підходять гачки SVN.