Документация это средство масштабирования отдела. Имея хорошую документацию легко можно увеличивать число сотрудников в отделе, и передавать задачи.
О пользе документации
Документация является средством обмена знаниями, а также средством достижения управляемости информационной средой. Без документации инфраструктуру нельзя назвать управляемой, она хаотична и зависима целиком и полностью от создателей. Руководство, которое инвестирует в инфраструктуру организации, немало переживает по этому поводу. Организация зависит от своих процессов, которые, в свою очередь, попадают в серьезную зависимость от информационных систем. Без документации информационные системы замыкаются на конкретных сотрудниках, что становится проблемой и для "незаменимого" сотрудника (должен быть доступен\работать 24\7, невозможно уйти в отпуск в удобное время и т.д.) и для организации, которая попадает в зависимость от носителя "тайных" знаний.
Это одна из возможных предпосылок к недоверию между руководством и представителями ИТ. Одни не желают делиться деньгами, другие – знаниями. Порочный круг, который необходимо разорвать, чтобы продолжить эффективно работать.
Подробная документация нужна руководству, чтобы чувствовать себя комфортно и уверенно.
- Подробная документация повышает значимость сотрудников ИТ в глазах руководства (руководство замечает серьезный системный подход, но не стоит забывать о том, что это необходимо подобающе презентовать).
- Другим немаловажным фактором является то, что документация жизненно необходима самим сотрудникам отдела ИТ.
- Процесс создания документации позволяет обнаружить и исправить имеющиеся проблемы.
- Процесс создания документации позволяет систематизировать и «обернуть в формы» имеющиеся представления об ИС, позволяет укрепить свои знания. Ведение технической документации повышает общий профессионализм ИТ отдела.
- Документация необходимый элемент для достижения взаимозаменяемости сотрудников отдела. Наличие хорошо подготовленной документации, позволяет решить большинство проблем при отсутствии специалиста.
- Документация ускоряет процесс вступления в должность новых сотрудников или передачу дел.
- Документация решает такую задачу как "воспроизводимость". С помощью хорошей документации можно воспроизвести любую часть инфраструктуры, причем руками уже других людей, но с тем же результатом. Повторить внедрение, интеграцию или масштабирование используемых систем. Никогда уже не услышите "Я там что-то потыкал оно заработало, почему именно так не знаю, но лучше не трогать". Пропадет страх перед внедрением изменений в ваши подсистемы. Принцип "работает не трогай" начнет работать в правильном применении, а не как фактор замедления развития инфраструктуры.
- Документация как следствие приводит к экономии времени. Не надо вспоминать сложные взаимосвязи систем, принципы работы технологий, нюансы реализаций. Экономит время при анализе систем, т.к. структура и схемы уже готовы к анализу.
- Созданная подробная документация призвана помогать в понимании того, «что», «как» и «почему». А т.к., людям свойственно забывать, то, как говорится, «Лучше плохой карандаш, чем хорошая память…».
Ведение документации самостоятельный сложный процесс требующий навыков и времени, но эти затраты в перспективе окупаются многократно.
Когда начинать вести документацию
Когда же надо начинать вести документацию на подотчётное «хозяйство»? Правильным ответом было бы – сразу. То есть ровно с того момента, как начала закладываться инфраструктура будущей организации. Пока ещё нет десятков метров непонятных сетевых, телефонных и прочих кабелей. Пока нет неразберихи. Тем более, что правильное планирование будущей сети компании с необходимыми планами, схемами и описаниями, это уже огромный задел для весьма увесистого и крайне подробного пакета технических документов. Но проектирование ИТ это удел крупных организаций. Поселковый сисадмин обычно имеет дело с наследием предыдущих "архитекторов", либо решает задачи по мере поступления. Задачи перед ним рисует бизнес, чей курс весьма изменчив, да и в известность ИТ ставят обычно в последнюю очередь, когда все решения уже приняты.
Если у вас ещё нет документации – начните прям сегодня. Ведь это только начало работы по написанию полноценного пакета документов на всё, с чем вы работаете. Как известно, Родина начинается с картинки в букваре, а техническая документация системного администратора со схемы структуры сети. Структура локальной сети может стать совсем запутанной, если вовремя не внести систему и порядок в неё.
Документировать всё
Если поставить среднего администратора перед выбором между установкой сервера с нуля и написанием подробной
документации по резервному копированию системы, он выберет переустановку. Так как переустановка обычное
действие, вы должны документировать, то что вы делаете. Это кажется бестолковым занятием, но на практике это очень полезно. Некоторые выявленные мелочи уже не будут забыты. В моменты когда нет времени задачу можно поручить другому сотруднику и не переживать о том, все ли вы ему рассказали о процессе или что-то упустили. И в целом достаточно полно описав выполнение задачи вы экономите время на повторных выполнениях, на делегировании задачи, на автоматизации\оптимизации некоторых участков или процесса целиком. Автоматизировать\оптимизировать неописанный процесс вряд ли возможно (разве что мелкий). Многие системные администраторы пренебрегают написанием необходимой документации по разным причинам:
«Я разберусь с этим потом».
К сожалению, обычно этого не происходит. И даже если системный администратор не хочет обмануть сам
себя, его работа по природе такова, что повседневные задачи слишком хаотичны, чтобы «делать это потом».
И что ещё хуже, чем больше это откладывается, тем больше забывается, и в результате получается менее
подробная, а значит и менее полезная документация.
«Зачем это записывать? Я и так это запомню.»
Нет, вы не запомните, если конечно вы не чудо природы с фотографической памятью. Или ещё хуже, вы
вспомните только часть, не осознавая того, что вы что-то упустили. В результате вы потратите время,
или пытаясь снова выяснить забытое, или исправляя то, что вы сломали, не имея полной картины ситуации.
«Если я буду держать всё в голове, меня не уволят — у меня будет защита от увольнения!»
Хотя некоторое время это может работать, затем такая защита от увольнения становится не лучше, а хуже.
На секунду представьте себе, что может произойти в экстренном случае. Если вас не будет на месте, ваша
документация может помочь кому-то решить проблему в ваше отсутствие и спасти день работы компании.
И никогда не забывайте о том, что именно в экстренных случаях руководство уделяет вашей работе наибольшее внимание.
В таких случаях лучше, чтобы ваша документация стала частью решения, чем ваше отсутствие — частью проблемы.
Кроме этого, если вы работаете в небольшой, но растущей компании, в один прекрасный день понадобится
ещё один системный администратор. Как он сможет узнать всё, что вы держите в своей голове? И что ещё
хуже, отсутствие документации может сделать вас настолько незаменимым, что это помешает вашему карьерному росту.
В итоге вы можете оказаться на месте того, кого приняли на работу вам в помощь.
Хочется надеяться, что эти преимущества документирования вас убедили. И перед нами встаёт следующий вопрос:
Что следует документировать? Ниже приведён неполный список:
Политики
Политики оформляются письменно, чтобы формализовать и чётко определить ваши отношения с сообществом
пользователей. Они также ясно говорят пользователям, как выполняются их запросы ресурсов и/или помощи.
Характер, стиль и способ распространения политик среди пользователей в разных организациях могут различаться.
Процедуры
Процедуры — это пошаговое описание действий, которые должны быть сделаны для выполнения определённой задачи.
В число документируемых процедур входят процедуры резервного копирования, процедуры управления учётными
записями пользователей, процедуры сообщения о проблемах и т.д. Как и с автоматизацией, если процедура
выполняется не один раз, будет правильно документировать её.
Изменения
Большая часть работы системного администратора связана с внесением изменений — настройка компьютеров
для увеличения производительности, манипуляции со сценариями, редактирование файлов конфигурации и т.д.
Все эти изменения следует каким-то образом документировать. В противном случае вы можете быть совершенно
озадачены изменением, которое вы внесли несколько месяцев назад.
Некоторые организации используют весьма сложные методы учёта изменений, но во многих случаев достаточно
всего лишь вести простую историю изменений в начале изменяемого файла. Каждая запись этой истории изменений должна содержать как минимум:
Имя или инициалы человека, внёсшего это изменение
- Дату и время изменения
- Причину внесения изменения
В результате вы получите лаконичные, но, тем не менее, полезные записи:
ECB, 12 июня 2002 — Изменена запись о новом принтере в бухгалтерии (отражена его возможность двусторонней печати)
Старайтесь располагать документацию как можно ближе к объекту документирования:
- комментарии к коду рядом с описываемой функцией
- электро схема в электрощитке
- комментарии на vlan в настройках коммутаторов
- id vlan'a в названии vlan'a
- маркировки на проводах
- комментарии к служебным учеткам и группам в АД.
- комментарии к виртуальным серверам и их интерфейсам.
- и т.д.
Маркировка
Маркировка физических объектов тоже является документацией, поэтому отнеситесь к ней серьезно и используйте системный подход. Цвета патчкордов в серверной обозначающие конкретный vlan или вид трафика всегда помогут быстро разобраться в физической топологии. Если у вас плотные жгуты красиво уложенных патчкордов, сохранить эту красоту поможет маркировка их с обоих концов. Тогда не придется при трассировке выпутывать патчкорды из жгутов. Делать такую маркировку конечно удобнее при первоначальном монтаже, но можно и позже. Маркировка портов на патчпанели и розеток сэкономит не мало времени при переездах и переключениях. А также при решении проблем со связью. Нанесение инвентарного номера(под которым числится в учетной системе) на устройства облегчит их учет и контроль. Именование и маркировка серверов снизит влияние и риски человеческого фактора. Например от случайной перезагрузки, можно будет отправить для нажатии кнопки на сервере совершенно любого человека, хоть охранника в 2 часа ночи 31 декабря. Так же это внесет однозначность, все администраторы будут называть один объект одним именем. Нередки случаи когда системные администраторы и веб администраторы одни и те же сервера называют по разному.
Одинаковая маркировка групп взаимосвязанных объектов экономит время в работе и снижает риски. Самый банальный пример это ряд автоматов и устройства, которые от них зависят. Маркировка должна быть простой и понятной. Например, на блоке розеток в стойке и на автомате маркировка "А1" может означать стойка "А", фаза "1". При таком подходе можно достаточно быстро установить связь, а время иногда очень критичный фактор. Риск ошибки и случайного отключения значительно снижается. Или например группа кондиционеров и их управление на СРК или просто группа пультов. Должно быть понятно каким пультом какой кондиционер управляется и в какое время какой кондиционер будет включаться согласно программе в СРК.
Инструменты
Вести документацию можно по разному. Кто-то любит бумагу, кто-то электронный вариант. Для обработки дополнения и поиска, электронный вариант лучше. Думаю большинство сразу подумало про wiki движки. Да они весьма неплохо подходят, если только вам нет необходимости рисовать схемы. Их можно вкладывать в wiki страничку, но рисовать придется в другом месте.
Redmine
Я рекомендую использовать Redmine, это бесплатная система ведения проектов, в том числе там есть и wiki. Удобно завести несколько проектов по направлениям, так можно структурировать документацию. Есть там полезные макросы и возможность включать одни документы в состав других. Таким образом изменив вложенный документ он изменится сразу во всех документах где учавствует и не придется править их все по отдельности. Также есть интеграция с LDAP, управление правами доступа и т.д. Набор полезных плагинов (в контексте ведения документации): Clipboard image paste, Include macro extension plugin, Redmine Lightbox 2, Redmine Wiki Sidebar TOC plugin, Redmine Tags, Redmine Wiki Notes plugin. Рекомендую использовать режим хранения Markdown, всегда и везде, он обеспечит переносимость документации между разными системами.
Gogs
Любители git могут использовать Gogs. Это аналог GitHub, который разворачивается локально. Все развертывание состоит в запуске бинарника и первоначальной настройки в веб интерфейсе. В репозиториях можно хранить документы в Markdown формате, по аналогии как это делается с файлом README.md в почти каждом репозитории Github. Но я рекомендую использовать его в дополнение к Redmine для хранения исходников скриптов, программ, конфигов...
Microsoft OneNote
Тем, кому сложно совладать с собой и начать записывать информацию в форматированном и структурированном виде, хорошо подойдет OneNote. Он позволяет вести документацию в виде быстрых заметок, при этом очень удобен затем в работе с этим хаосом. Есть определенные ограничения по структурированию, но я думаю вряд ли ваша документация разрастется до таких масштабов на этом инструменте. Зато можно будет быстро скринить и добавлять заметки в произвольные места документа, а также делать зарисовки.
draw.io
Для большинства схем подойдет draw.io. Это аналог Microsoft Visio. Диаграммы можно экспортировать в PNG и вставлять в документацию как рисунок, но при этом важно сохранять диаграмму как xml (File-> Save as, или Ctrl+Shift+S) и прикреплять к документу, чтобы в последствии ее можно было редактировать, а не рисовать заново.
Hugo (статический генератор сайтов)
Можно использовать, какой-либо статический генератор сайтов, например, hugo. Ведение документации будет представлять ведение файлов в формате Markdown из которых будет строится сайт. Существует множество тем для отрисовки, можно выбрать подходящую. А сами файлы можно хранить в Gogs, чтобы иметь историю редактирования.
Файлы
Можно вести документацию и в текстовых файлах или файлах офисных пакетов, раскладывая их по папкам. На мой взгляд это самый неудобный вариант. Но если вам проще начать с такого варианта, то лучше начать с него, чем тратить время на изучение непонятных инструментов и так и не начать ведение документации.
ПАРОЛИ ЯВЛЯЮТСЯ ЧАСТЬЮ ДОКУМЕНТАЦИИ, НО ХРАНИТЬСЯ И ОБРАБАТЫВАТЬСЯ ДОЛЖНЫ ОТДЕЛЬНО ОТ ДОКУМЕНТОВ! Документацию вы должны передавать другим людям свободно и без риска.
Пишите в комментариях чем вы пользуетесь для ведения документации и какие интересные решения нашли. За жирную статью ставьте жирный лайк!
