Как правильно вести техническую документацию Системному администратору?

Подскажите, кто поопытней. Как должна выглядеть техническая документация системного администратора? Или это все делается в произвольной форме?
  • Вопрос задан
  • 8039 просмотров
Решения вопроса 6
@leobatura
network engineer
С опытом пришло понимание, что должно быть вот так:

1) Идёшь в бухгалтерию, берешь там список имущества, которое числится на тебе / на отделе, проходишь по всем -- сверяешь, вплоть до старой гарнитуры, всё должно сойтись. Лицензии на ПО точно также. Ты должен в любой момент времени точно сказать -- где, что и сколько у тебя стоит, сколько на складе, что ты заказал, что пришло и то ли пришло. Для бухгалтерии это всё коробочки с лампочками. ОБЯЗАТЕЛЬНО! должны биться серийные номера. Если их нет требуй присвоить инвентарный. Даже на картридже для принтера. Если условная Света из логистики принесла свою мышь, у тебя должно быть это отображено. Всё с парком машин происходить только с твоего ведома.
Не бойся обращаться к руководству -- оно оценит, что ты экономишь их деньги.
Всё, что ты выдаешь -- выдавай под роспись. Это дисциплинирует.

2) Схема сети. Видеонаблюдение и телефония. Как нарисованная, так и WeatherMap в Cacti. Многие ей пренебрегают, почем зря. Ты всегда должен знать что у тебя происходит с каналами связи. Все вланы, все адреса, местоположение должно быть отражено и подписано. Все стойки и шкафы должны быть сфотографированы, так чтобы было чёткое понимание, что-куда-зачем.
Поверь, в случае аварии тебе это очень сократит время на восстановление.
aid1284150-v4-900px-Create-a-Network-Doc

3) Маркировка оборудования. Всё, нет не так -- ВСЁ!!! должно быть подписано. Все розетки, все патчи. Вообще всё!

4) Делаешь себе локальную вики, пох на чем и пишешь туда АБСОЛЮТНО всё. Как настроить порт на коммутаторе, набор основных команд, диагностика, версия прошивки, какая-то основная конфигурация. Бэкапы конфигурации храни в текстовом виде, не доверяй всяким .cfg, как настроить vlan на микроте, как поднять VPN до соседнего офиса.
Тебе это очень сильно сократит время, особенно некоторые операции надо проводить довольно редко.

5) Пиши скрипты для рутины. Скрипты тоже должны быть в вики.
Допустим обновить 5 коммутаторов или поправить ACL ненапряжно. А если их 50? 150?

6) В вики не должно быть ни одной ссылки на сторонние ресурсы. Завтра страница переедет, а ты на нее надеялся.

7) У тебя должны быть контакты всех поставщиков услуг, что касается твоего отдела: провайдеров, заправщиков, инженеров, горсетей, номера договоров, и прочая херня Если что-то случилось, ты должен очень быстро получить ответы, а не ждать на горячей линии. Держи контакты актуальными.

8) Чтобы это всё имело хоть какой-то смысл -- трать 1 час в день, чтобы заняться документацией. Иначе всё это херня.
Ответ написан
CityCat4
@CityCat4 Куратор тега Сетевое администрирование
Внимание! Изменился адрес почты!
Да как угодно. Главное - она должна быть. И быть актуальной.
Ответ написан
Комментировать
@Madguy
System Engineer, student in MTUCI
Присоединяюсь ко всем, кто высказывает я в пользу наличия аккуратно документации. Ниже приведу принципы, которыми успешно пользуюсь сам. Надеюсь, они помогут вам сформировать свое мнение и встать на "светлую сторону" силы.

Сначала скажу о плюсах документации:
- она помогает вам учиться грамоно структурировать информацию
- есть хорошая вероятность, что в будущем вы сами сможете ею воспользоваться и скажете себе "спасибо" (проверено)
- ею сможет воспользоваться ваш преемник или коллега/руководитель. И, если от преемника вы маловероятно получите какую-либо выгоду кроме морального удовлетворения, то ваш во 2-ом случае это сыграет вам на пользу. Вам будет проще объяснить своему коллеге (да и руководителю) принцип работы, чтобы втянуть его в работу. Руководитель сможет увидеть один из результатов вашей работы, и вы станете более ценным сотрудником в его глазах.
Тут ещё куча плюсов может нарисоваться, но это самые главные.

Принципы:
- пишите документацию так, чтобы человек с минимальными знаниями по теме мог разобраться о чем идёт речь
- в большинстве статей вы скорее всего будете описывать решение конкретной задачи
- остальные статьи, верятно, будут иметь описател ный характер (схема сети, расмещение серверов, список доменов, список можете продолжить сами)
- описывайте только главное, не углубляйтесь в подробности и основы. Для этого есть официальная документация. Вместо описывания основ, дайте ссылку на документацию и пометьте какую информацию там можно найти.
- ведите структурированную документацию там, где возможно. Введите минимал ные разделы: "описание", "ссылки", "инструкция". "Описание" - здесь пишите какую проблему решаете и что получаете на выходе. "Ссылки" - собираете тут все ссылки, которые указали в статье. "Инструкция" - тут непосредственно сами шаги, которые привели вас к нужному результату. Также в начале этого раздела можно привести список требований (наличие root/админского доступа, наличие нестандартных настроек приложенияя/веб-сервера/системных настроек и тд).
- в описании или в начале инструкции дайте пару основных определений, которыми будете оперировать в статье.
- не стесняйтесь приводить иностранную документацию и ссылки, а также не забывайте сами её читать. Сегодня есть отличные инструменты для этого, даже если вы не знаете другой язык. Встроенный переводчик в Google Chrome может перевести сразу всю страницу. Расширение для Google Chrome - LinguaLeo может перевести конкретное слово (пр двойном нажатии на слово)

Хорошая документация не обязательно требует наличия красивых схем и скриншотов. В большинстве случаев достаточно аккуратного описания. Но в некоторых случаях могут понадобится схемы. Тут можно использовать как скриншоты, так и сделать схему самому. Очень гибкий бесплатный веб инструмент для разных схем - draw.io

На этом пока все. Есть ещё куча подходов и принципов, а также много литературы и где-то завалялся недавний выпуск подкаста. Если будет интересно - скину, а то с планшета неудобно
Ответ написан
Легко начать с ДокуВики. Эта Вики проста в установке (1 пакет в Линуксе) и использовании и неоднократно помогала мне в работе. Не нужны никакие папки с кучей документов, а есть информационная система с поиском, База Знаний.
Легко пополнять постепенно, не заостряя внимание на конкретном документе.
Ответ написан
eduardtibet
@eduardtibet
Technical Writer / Documentation Engineer
ILoveVMware
Уже был ответ по технической составляющей вопроса: какой формат и как хранить.
Ответ написан
Комментировать
Пригласить эксперта
Ответы на вопрос 2
LESHIY_ODESSA
@LESHIY_ODESSA
Я использую — OutWiker.
Ответ написан
Комментировать
fdroid
@fdroid
press any key
Техническую документацию вести вообще не нужно, всё должно быть у сисадмина в голове. Одни плюсы:

1) Тренировка памяти.
2) Никому нафиг не нужна ваша документация, потому что вы и так всё знаете, а ваш преемник всё равно не разберётся в том, что вы там наворотили, всё грохнет и настроит заново, под свои требования.
3) Вам больше делать нечего чтобы тратить время на ведение того, что кроме вас никто читать не будет?
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы