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

Question

[Алексей Артюшевский]

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

Answer 1

[Леонид]

С опытом пришло понимание, что должно быть вот так:

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

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


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

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

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

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

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

8) Чтобы это всё имело хоть какой-то смысл -- трать 1 час в день, чтобы заняться документацией. Иначе всё это херня.

Comments

[Алексей Артюшевский]

Спасибо! Очень развернуто!

[Exe Onid]

схоронил

Answer 2

[CityCat4]

Да как угодно. Главное - она должна быть. И быть актуальной.

Answer 3

[Максим Шепелев]

Присоединяюсь ко всем, кто высказывает я в пользу наличия аккуратно документации. Ниже приведу принципы, которыми успешно пользуюсь сам. Надеюсь, они помогут вам сформировать свое мнение и встать на "светлую сторону" силы.

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

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

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

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

Comments

[Максим Шепелев]

Ах да, хотел ещё высказаться про то, где вести документацию.
Тут 2 вопроса:
- в чем вести рабочую доку
- в чем вести личные доки (конспекты). Об этой необходимости в самом низу, а то помидорами закидают за полемику.

В принципе, вы свободны выбрать любой понравившиеся инструмент, но принцип везде один: использования morkdown, чтобы аккуратно структурировать доки. Markdown везде примерно одинаковый, поэтому тут все сводится к инструменту, в котором удобнее всего видеть результат своей работы. Это может быть как предпросмотр (Redmine) , так и визуализация в реальном времени (удобнее: Confluence или даже Word). Из примеров выше слышал про DocuWiki, но советую выбрать для себя вариант, к которому ляжет сердце.
Установка какой-либо платформы сегодня может оказаться очень простой, если освоите docker, пропишите настройки в docker-compose и смонтируете важные данные на диск. Это позволит вам легко бекапить, обновлять саму платформу и переезжать на другие сервера.

Можно, конечно вести документацию в вордоских файликах/или даже .txt, но вы же профессионал, готовы изучать новые технологии и стремиться к прекрасному! (извините, заболтался)

По поводу ведения заметок и конспектов.
Те, кто тренируют свою память молодцы, но ограничены в своих возможностях. Они вряд ли смогут вам за 5-10 минут наглядно объяснить принцип работы протокола bgp или схема работы кластера Ceph. Да, они знают как это настроить и как работает, но но могут популярно объяснить вам почему pool size 2 менее безопасно для продакшена, чем 3 и каким последствиям это может привести.
Изучая новые технологии поначалу будет большой соблазн просто запоминать. Но эти знания не нужны вам в вашей голове 100% времени. Вы можете увеличивать объем оперативной памяти вашего сервера, но до определённого предела (да, сегодня этот предел может быть огромным),но дешевле купить магниты или даже ленту (не делайте так) и слить инфу туда (но для этого придётся составить структурированную конспект). Оперативаня память может пригодиться для других повседвеных задач как список дел, продуктов, вспомнить поздравить бабушку с днем рождения или обсудить последний сезон игры престолов.

Освоив ведение Базы Знаний, вам, вероятно, захочется продолжить ведение личных коспектов в ней же. Сегодня и это можно сделать. Арендуете минимальный серверов где-нибудь в AWS, DO, GCP, Яндекс облако и разворачивается свою БЗ там с помощью того же docker'a (docker-compose ftw). Есть и более бюджетные площадки в основном иностранные типа Aruba, scaleway и подобных. Я пользуюсь Aruba cloud для личных целей за 1€ в месяц (правда с 2019 они ввели НДС и повысили цены для новых серверов, но за старый я по-прежнему почему-то плачу по 1€).
Если разворачивать свой VPS нет желания, можно вести свои конспекты в текстовых файликах (да, можно научиться структурировать информацию даже в.txt. Табы, строчки спецсимволов вам в помощь, будьте креативны!) и сливать в приватный Git репозиторий. На Github они платные, зато на Gitlab бесплатные. Это также сделает ваши заметки высоко доступными и легко скачиваемыми.
Также можно использовать бесплатные гиги на GoogleDrive/Dropbox и тп, т. к. там есть заманчивые функции онлайн-редактирования. Но лично мне они не удобны (уже пытался вести там конспекты): анимация подтормаживает, когда файлы становятся непомерно большими; когда есть несколько файлов, они долго открываются.

Приятного ведения документации, не забывайте изучать новые вещи и создавать свои.

Answer 4

[Михаил Лялин]

https://it.wikireading.ru/58247
https://system-administrators.info/?p=17

Answer 5

[d'Ivan]

Легко начать с ДокуВики. Эта Вики проста в установке (1 пакет в Линуксе) и использовании и неоднократно помогала мне в работе. Не нужны никакие папки с кучей документов, а есть информационная система с поиском, База Знаний.
Легко пополнять постепенно, не заостряя внимание на конкретном документе.

Comments

[Валентин]

Xwiki мне больше зашла

Answer 6

[Эдуард Тибет]

ILoveVMware
Уже был ответ по технической составляющей вопроса: какой формат и как хранить.

Answer 7

[LESHIY_ODESSA]

Я использую — OutWiker.

Answer 8

[fdroid]

Техническую документацию вести вообще не нужно, всё должно быть у сисадмина в голове. Одни плюсы:

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

Comments

[vanoc]

Ерунду несёте, уважаемый. Помнить все невозможно. Хорошо можно помнить только то, чем занимаешься каждый день. Это как с иностранными языками. И даже если кому-то ещё ваши заметки не пригодятся, важно то, что они ни раз пригодятся вам самим. Гораздо быстрее будет заглянуть в свои заметки, когда помнишь, что делал что-то подобное, чем гуглить и изобретать колесо заново.

[vanoc]

Ещё раз перечитал ваш ответ и появилось стойкое ощущение, что вы троллите. Эх. А я повелся :(

[20ivs]

vanoc, это чей-то преемник, которому не оставили документации =)

[Максим Шепелев]

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

[20ivs]

Madguy, категорически поддерживаю.

[fdroid]

20ivs,

это чей-то преемник, которому не оставили документации =)

да, было дело. Пришёл работать в немаленькую сеть: несколько серверов, куча виртуалок, вланов, подсетей, управляемых коммутаторов и т.д. Пользовательские компы не считаю даже. Из документации был только вордовский документ, в котором почти ничего не было, а что было - далеко не всегда соответствовало действительности. Т.е. ни логинов, ни паролей, ни IP, ни схем - ничего. Повторяю по буквам - Николай, Илья, Харитон, Ульяна, Яков - ничего. Вот весело-то было. Админ ушёл не то что со скандалом, но нервно. Возможно, он думал, что незаменим и всё пойдёт по звезде без него. Но не пошло. Пол-года только упорядочивал всё, инвентаризировал, рисовал схемы, и т.д. Ну и, конечно, текучку и авральчики никто не отменял. В итоге, я оттуда ушёл - не устроила з\п, обещанное повышение после "испытательного срока" как-то не наступило.

[20ivs]

fdroid, прекрасно понимаю. работал в аутсорсе когда-то. приходишь к новому клиенту, админа нет уже сто лет в обед. на слово "документация" у контактного лица реакция одна - "документы подписать? давайте!"
лишь однажды у клиентов нашел где-то в углу серверной в куче говна записную книжку админа, после которого было еще двое. как он всё настроил, установил, в блокнот записал, так больше никто там ничем и не занимался.