Полезная бюрократия: зачем сайту инструкция по эксплуатации?

Полезная бюрократия: зачем сайту инструкция по эксплуатации?

Привет, это ITSumma, и да, мы чутка преувеличили: понятное дело, что у сайта — с бытовой точки зрения — не может быть инструкции по эксплуатации. Но она может быть (и должна быть) у инфраструктуры веб-проекта. Зачем и как её создать и в чём выгода для бизнеса от небольшой бюрократизации в IT — рассказываем откровенно и с примерами.

Что такое инфраструктурная документация

Вначале — бытовой пример. Если вы когда-то покупали машину, то знаете, что вместе с ключами дилер передаёт вам толстенное руководство по эксплуатации.

Опрошенные нами 37 автовладельцев из числа коллег признались, что ни разу в неё не заглядывали. Ещё 12 были вынуждены заглянуть, когда с автомобилем случилась какая-то неприятность. То есть инструкция в нашем бытовом понимании — такая необязательная штука, которая нужна только когда что-то ломается.

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

Но есть и отличия — важные, ключевые:

  • инфраструктурная документация постоянно пополняется;
  • новому сотруднику без знакомства с ней практически невозможно “сесть за руль и поехать” — ведь внутреннее устройство каждой инфраструктуры уникально (в отличие от автомобиля);
  • она помогает экономить деньги.

В чём выгода для бизнеса

Ведение документации — процесс, который требует определённых ресурсов. Почему же эти издержки стоят того?

  1. Коммуникации эффективнее.
  2. Риски меньше.
  3. Планирование лучше.

Поясним за каждый тезис подробно.

Улучшение внутренней коммуникации

Этот тезис выглядит как мудрость от Капитана, но дочитайте: наличие документации, содержащей подробное описание ИТ-систем компании, помогает сотрудникам лучше понимать, как работают эти системы и как они взаимодействуют друг с другом. Соответственно, поэтому проблемы решаются быстрее и эффективнее.

Бонус: прозрачность в понимании того, как всё устроено, помогает находить “точки роста” — проще говоря, где что можно улучшить.

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

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

Уменьшение рисков и повышение безопасности

Документированные процессы помогают компании лучше понимать, как изменения в инфраструктуре будут влиять на бизнес. И что сделать, если негативного влияния не удалось избежать – проще говоря, как откатиться на исходные в случае ошибки или серьёзного инцидента.

Полезная бюрократия: зачем сайту инструкция по эксплуатации?

Бонус: если специалист, владеющий информацией о внутреннем устройстве системы, уволился, риск столкнуться с непознанным практически сводится к нулю — опять же, благодаря тому, что эти знания не только у него в голове, но и в документации.

Улучшение планирования и управления

Документация помогает зафиксировать лишние компоненты в инфраструктуре. В ней чётко видны те модули, которые потеряли свою актуальность и не используются или дублируют функции других элементов. Таким образом, чем подробнее документация — тем больше возможностей оптимизировать издержки.

В документах обязательно должна быть полная схема инфраструктуры: серверы, их IP-адреса, сервисы, которые работают на этих серверах, домены и их проксирование, репликации и синхронизация.
В документах обязательно должна быть полная схема инфраструктуры: серверы, их IP-адреса, сервисы, которые работают на этих серверах, домены и их проксирование, репликации и синхронизация.

Какой должна быть инфраструктурная документация

Полной, актуальной, структурированной и единообразной.

Как сделать её полной?

Нужно составить инвентори — полный список ресурсов проекта. Это виртуальные и железные серверы, облачные ресурсы и сервисы и т.д.

Ещё здесь указываются такие характеристики, как количество процессоров, объём оперативной памяти, способы доступа к тому или иному ресурсу, если они имеют какие-то особенности. Также в инвентори стоит отразить расположение ресурсов проекта — в каких датацентрах, у каких хостеров или на каких железных серверах они находятся.

И, наконец, этот список ресурсов описывает всё IT-хозяйство вашего бизнеса — сайты, приложения и существующие среды (контуры для разработки, тестирования и т.д.)

<p>Пример, как может выглядеть инвентори</p>

Пример, как может выглядеть инвентори

Как сделать её актуальной?

Документация должна меняться вслед за изменениями в инфраструктуре, при этом сохраняя всю историю изменений.

Когда нужно обновлять инструкции и документацию:

  • при добавлении или удалении серверов, продуктов и приложений;
  • во время миграции в новый ДЦ или облако;
  • если вы стали использовать новые инструменты для работы проекта.

Как сделать её структурированной и единообразной?

В этом поможет стайлгайд. Он обеспечивает консистентность документов и ускоряет адаптацию новых сотрудников благодаря структурированию информации.

Дословный перевод английского словосочетания Style guide — «руководство по стилю». Применительно к документации это набор правил и требований, включающий особенности стиля и тона изложения, оформления текста и структуры, использования терминологии и т.д.

Что дает стайлгайд:

  • Приводит документы к единому виду. Это помогает быстрее и проще ориентироваться в них.
  • Уменьшает время на подготовку новых инструкций.
  • Формализует знания, которые ранее хранились в головах разных людей.
Пример нашего стайлгайда
Пример нашего стайлгайда

Резюмируем

Можно ли жить без инфраструктурной документации? — Конечно. Люди же ездят на автомобилях, стирают в стиральных машинах, взбивают смузи в блендерах, ни разу не прочитав инструкцию по эксплуатации ко всем этим устройствам.

Лучше ли бизнесу от ведения документации? — Безусловно! Это облегчает поиск источников проблем, когда они происходят, помогает новым сотрудникам быстрее вникнуть в суть процессов и умножает возможности сэкономить на инфраструктуре.

Сложно ли организовать этот процесс? — Просто, если следовать проторенному нашей компанией пути:

  • составить инвентори,
  • описать взаимодействие между компонентами системы,
  • фиксировать все изменения в инфраструктуре.

Нужен совет, как запустить процесс? — Советом всегда поможем! Пишите нам на consulting@itsumma.ru

И да пребудет с вами сила печатного слова ;-)

15
1 комментарий

Раньше занимался реализацией сайтов на питоне, инструкции даже к дружелюбной и обычной админке приходилось ваять)

Ответить