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

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

Какие бывают схемы

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

Дисклеймер: это продолжение темы о составлении правильной технической документации. В первой статье мы рассказали, какие цели преследуются при составлении инфраструктурной документации и какие у нее особенности. А теперь поговорим о том, как составить годный стайлгайд, чтобы документы были удобочитаемыми, консистентными и… может быть, даже красивыми :-)

Что такое стайлгайд?

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

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