Привет, это ITSumma, и да, мы чутка преувеличили: понятное дело, что у сайта — с бытовой точки зрения — не может быть инструкции по эксплуатации. Но она может быть (и должна быть) у инфраструктуры веб-проекта. Зачем и как её создать и в чём выгода для бизнеса от небольшой бюрократизации в IT — рассказываем откровенно и с примерами.
Что такое инфраструктурная документация
Вначале — бытовой пример. Если вы когда-то покупали машину, то знаете, что вместе с ключами дилер передаёт вам толстенное руководство по эксплуатации.
Опрошенные нами 37 автовладельцев из числа коллег признались, что ни разу в неё не заглядывали. Ещё 12 были вынуждены заглянуть, когда с автомобилем случилась какая-то неприятность. То есть инструкция в нашем бытовом понимании — такая необязательная штука, которая нужна только когда что-то ломается.
Инфраструктурную документацию отчасти тоже можно назвать инструкцией по эксплуатации веб-проекта. С её бытовым аналогом их роднит то, что в документации содержится описание устройства продукта или системы и взаимодействии их частей, как ими пользоваться, какие могут быть проблемы и как их решать.
Но есть и отличия — важные, ключевые:
- инфраструктурная документация постоянно пополняется;
- новому сотруднику без знакомства с ней практически невозможно “сесть за руль и поехать” — ведь внутреннее устройство каждой инфраструктуры уникально (в отличие от автомобиля);
- она помогает экономить деньги.
В чём выгода для бизнеса
Ведение документации — процесс, который требует определённых ресурсов. Почему же эти издержки стоят того?
- Коммуникации эффективнее.
- Риски меньше.
- Планирование лучше.
Поясним за каждый тезис подробно.
Улучшение внутренней коммуникации
Этот тезис выглядит как мудрость от Капитана, но дочитайте: наличие документации, содержащей подробное описание ИТ-систем компании, помогает сотрудникам лучше понимать, как работают эти системы и как они взаимодействуют друг с другом. Соответственно, поэтому проблемы решаются быстрее и эффективнее.
Бонус: прозрачность в понимании того, как всё устроено, помогает находить “точки роста” — проще говоря, где что можно улучшить.
И наконец, с помощью документации новые сотрудники быстрее приступят к своим обязанностям и разберутся, как работает проект, как построена и из чего состоит его инфраструктура.
Уменьшение рисков и повышение безопасности
Документированные процессы помогают компании лучше понимать, как изменения в инфраструктуре будут влиять на бизнес. И что сделать, если негативного влияния не удалось избежать – проще говоря, как откатиться на исходные в случае ошибки или серьёзного инцидента.
Бонус: если специалист, владеющий информацией о внутреннем устройстве системы, уволился, риск столкнуться с непознанным практически сводится к нулю — опять же, благодаря тому, что эти знания не только у него в голове, но и в документации.
Улучшение планирования и управления
Документация помогает зафиксировать лишние компоненты в инфраструктуре. В ней чётко видны те модули, которые потеряли свою актуальность и не используются или дублируют функции других элементов. Таким образом, чем подробнее документация — тем больше возможностей оптимизировать издержки.
Какой должна быть инфраструктурная документация
Полной, актуальной, структурированной и единообразной.
Как сделать её полной?
Нужно составить инвентори — полный список ресурсов проекта. Это виртуальные и железные серверы, облачные ресурсы и сервисы и т.д.
Ещё здесь указываются такие характеристики, как количество процессоров, объём оперативной памяти, способы доступа к тому или иному ресурсу, если они имеют какие-то особенности. Также в инвентори стоит отразить расположение ресурсов проекта — в каких датацентрах, у каких хостеров или на каких железных серверах они находятся.
И, наконец, этот список ресурсов описывает всё IT-хозяйство вашего бизнеса — сайты, приложения и существующие среды (контуры для разработки, тестирования и т.д.)
Пример, как может выглядеть инвентори
Как сделать её актуальной?
Документация должна меняться вслед за изменениями в инфраструктуре, при этом сохраняя всю историю изменений.
Когда нужно обновлять инструкции и документацию:
- при добавлении или удалении серверов, продуктов и приложений;
- во время миграции в новый ДЦ или облако;
- если вы стали использовать новые инструменты для работы проекта.
Как сделать её структурированной и единообразной?
В этом поможет стайлгайд. Он обеспечивает консистентность документов и ускоряет адаптацию новых сотрудников благодаря структурированию информации.
Дословный перевод английского словосочетания Style guide — «руководство по стилю». Применительно к документации это набор правил и требований, включающий особенности стиля и тона изложения, оформления текста и структуры, использования терминологии и т.д.
Что дает стайлгайд:
- Приводит документы к единому виду. Это помогает быстрее и проще ориентироваться в них.
- Уменьшает время на подготовку новых инструкций.
- Формализует знания, которые ранее хранились в головах разных людей.
Резюмируем
Можно ли жить без инфраструктурной документации? — Конечно. Люди же ездят на автомобилях, стирают в стиральных машинах, взбивают смузи в блендерах, ни разу не прочитав инструкцию по эксплуатации ко всем этим устройствам.
Лучше ли бизнесу от ведения документации? — Безусловно! Это облегчает поиск источников проблем, когда они происходят, помогает новым сотрудникам быстрее вникнуть в суть процессов и умножает возможности сэкономить на инфраструктуре.
Сложно ли организовать этот процесс? — Просто, если следовать проторенному нашей компанией пути:
- составить инвентори,
- описать взаимодействие между компонентами системы,
- фиксировать все изменения в инфраструктуре.
Нужен совет, как запустить процесс? — Советом всегда поможем! Пишите нам на [email protected]
И да пребудет с вами сила печатного слова ;-)
Раньше занимался реализацией сайтов на питоне, инструкции даже к дружелюбной и обычной админке приходилось ваять)