├── .media ├── TechnologicalMapExample.xlsx ├── competence_map_1_0.png ├── tech-map-excel.png ├── tech-map.png └── typical_steps.png ├── LICENSE ├── README.md ├── competence.md ├── debriefing.md ├── plan.md ├── tech-articles.md └── techmap.md /.media/TechnologicalMapExample.xlsx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devopshq/dohq-doc-templates/dacf5b103a34d595f0ad842950b5d261aba6b450/.media/TechnologicalMapExample.xlsx -------------------------------------------------------------------------------- /.media/competence_map_1_0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devopshq/dohq-doc-templates/dacf5b103a34d595f0ad842950b5d261aba6b450/.media/competence_map_1_0.png -------------------------------------------------------------------------------- /.media/tech-map-excel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devopshq/dohq-doc-templates/dacf5b103a34d595f0ad842950b5d261aba6b450/.media/tech-map-excel.png -------------------------------------------------------------------------------- /.media/tech-map.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devopshq/dohq-doc-templates/dacf5b103a34d595f0ad842950b5d261aba6b450/.media/tech-map.png -------------------------------------------------------------------------------- /.media/typical_steps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devopshq/dohq-doc-templates/dacf5b103a34d595f0ad842950b5d261aba6b450/.media/typical_steps.png -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Open DevOps Community 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # dohq-doc-templates 2 | 3 | Всем инженерам периодически бывает нужно структурировать свою работу и отчётность. Этот репозиторий содержит шаблоны инженерной документации для упрощения и сопровождения различных регламентных работ. Они были созданы в процессе повседневной работы DevOps-инженеров и автоматизаторов. Шаблоны могут пригодиться вашим инженерам для разработки регламентов и внутренней технической документации. 4 | 5 | **Шаблоны:** 6 | 1. [Карта компетенций инженеров DevOps](./competence.md) 7 | 2. [Технологическая карта производственного процесса](./techmap.md) 8 | 3. [Анализ и планирование работ по долгосрочным задачам](./plan.md) 9 | 4. [Разбор полётов (постмортем, debriefing)](./debriefing.md) 10 | 5. [Содержание коротких технических статей](./tech-articles.md) 11 | -------------------------------------------------------------------------------- /competence.md: -------------------------------------------------------------------------------- 1 | # Карта компетенций инженеров DevOps 2 | 3 | Более подробно про то, как мы видим развитие инженеров DevOps, рост их компетенций: знаний, умений и навыков, можно почитать в статье на Хабре: "[Личный опыт: как выстроить карьерный рост в отделе DevOps](https://habr.com/ru/company/pt/blog/501766/)" 4 | 5 | В этой инструкции расскажем, что такое "карта компетенций" и как её можно представить с учётом особенностей работы своего отдела. 6 | 7 | ## Знания, умения и навыки 8 | 9 | Когда увеличивается количество продуктовых конвейеров, находящихся на поддержке инженеров DevOps, то растёт и развивается и сам отдел. Становится понятно, что по каждому направлению работ не получится описать однозначную роль и найти подходящего инженера на рынке труда. От инженеров часто ожидают наличия кросс-навыков. 10 | 11 | У каждого DevOps-отдела своя специфика работы. Например, очевидно, что команде не нужен мегаквалифицированный программист разработчик ПО для решения CI-задач, но тем не менее CI-инженер должен уметь программировать небольшие модули и скрипты на Python на приемлемом уровне. Точно также бывает не нужен мегаквалифицированный Linux-администратор, но команде DevOps всегда нужен человек с достаточными знаниями ОС Debian или Ubuntu, чтобы он сумел установить на них сборочные агенты GitLab CI, а еще лучше — автоматизировал эти работы через SaltStack, Ansible или другие инструменты. 12 | 13 | Так что же должен уметь делать DevOps-инженер? Для начала определимся с понятиями, что такое знания, умения и навыки (сокращенно ЗУН) в общепринятом понимании. 14 | 15 | * **Знания** — это основные закономерности предметной области, позволяющие человеку решать конкретные производственные, научные и другие задачи, то есть факты, понятия, суждения, образы, взаимосвязи, оценки, правила, алгоритмы, эвристики, а также стратегии принятия решений в этой области. Знания — это также элементы информации, связанные между собой и с внешним миром. 16 | * **Умения** — под ними понимают освоенный человеком способ выполнения действия, обеспеченный некоторой совокупностью знаний. Умение выражается в способности осознанно применять знания на практике. 17 | * **Навыки** — это автоматизированные действия человека, которые вырабатываются в процессе сознательного выполнения определенных рабочих операций. То, что данное действие стало навыком, означает, что человек в результате упражнений приобрел возможность осуществлять рабочие операции, не делая это выполнение своей сознательной целью. 18 | 19 | Если вы сумеете определить ЗУН более конкретно, применительно к разрабатываемым в вашей компании продуктам, то у вас получится общий список компетенций инженеров DevOps или **Карта компетенций**. Без овладения этими конкретными компетенциями у инженера не получится качественно работать в компании. Список может получиться очень длинным, но это не страшно, потому что необходимо учитывать специфику работы сразу по всем направлениям, технологиям, процессам и продуктам. 20 | 21 | ## Карта компетенций 22 | 23 | Карту компетенций проще всего представить в виде таблицы. В ней необходимо описать и классифицировать все требования к инженеру. Выглядеть она может, примерно, так: 24 | 25 | ![](./.media/competence_map_1_0.png) 26 | 27 | Обозначения в таблице должностей сотрудников DevOps (в столбцах): 28 | 29 | * (**С**)тажёры, либо проходящие испытательный срок на должности младших инженеров или программистов 30 | * (**М**)ладшие инженеры или программисты 31 | * (**И**)нженеры или (**П**)рограммисты 32 | * (**Ст**)аршие инженеры или программисты 33 | * (**В**)едущие инженеры или программисты 34 | 35 | Таблица разбивается на четыре крупные секции (по строкам): 36 | 37 | 1. **Описание общих компетенций** сотрудников DevOps-отдела, необходимые для успешного решения повседневных задач. 38 | 2. **Знания** — специфические, ориентированные на конкретный продукт знания инженеров DevOps. 39 | 3. **Умения** — способности применить знания на практике для решения продуктовых задач; умение работать с используемыми в компании инструментами и технологиями. 40 | 4. **Навыки** — профессиональное владение используемыми в компании инструментами и технологиями; изученные и доведенные до автоматизма действия при решении типовых задач, не требующие особых усилий для их выполнения. 41 | 42 | В ячейках таблицы указываются **качественные оценки**: на каком уровне примерно должен владеть инженер той или иной компетенцией. **Условные целевые оценки** требований по компетенциям и ЗУН для сотрудников различных уровней могут быть, например, такие: 43 | 44 | * **0** — нет знаний, умений и практических навыков по данному требованию, либо они не обязательны для данной должности 45 | * **1** — есть теоретические знания по данному требованию и умение применить их на практике, возможно с помощью коллег или гуглинга 46 | * **2** — сотрудник знает данную тему хорошо и самостоятельно применяет навыки при решении типовых задач 47 | * **3** — сотрудник эксперт в данном вопросе и наработанные практические навыки может применить к решению любой задачи 48 | 49 | Для лучшего отражения динамики, можно использовать промежуточные оценки, с шагами **+0.1**, **+0.5**. Все требования к определённой должности по умолчанию включают в себя все требования предыдущей должности. 50 | 51 | В каждой компании и в каждом отделе DevOps нужно составлять свою аналогичную таблицу, учитывая специфику работы. Здесь также конкретизируются инструменты и технологии, которые обычно очень абстрактно описывают в формальных должностных инструкциях. 52 | -------------------------------------------------------------------------------- /debriefing.md: -------------------------------------------------------------------------------- 1 | # Разбор полётов 2 | 3 | **"Разборы полётов"** (дебрифинги, постмортемы и т.п.) — это инженерные документы, где чётко фиксируются: 4 | - хронология проблем и событий, возникших в ходе эксплуатации инфраструктуры, конкретного сервиса или ПО, 5 | - гипотезы причин возникновения проблем и инцидентов, 6 | - планы работ по их устранению, 7 | - рекомендации и шаги возможных улучшений, чтобы не допустить повторения проблем. 8 | 9 | Разборы полётов используются инженерами для того, чтобы в будущем спокойно проанализировать событие, выявить слабые места инфраструктуры, продумать и зафиксировать в виде задач конкретные действия, или предусмотреть дополнительную автоматизацию и тестирование, чтобы проблема вновь не возникла. 10 | 11 | Рекомендуется заранее подготовить шаблон документа для разбора полётов, чтобы во время активной работы над устранением проблемы ваши инженеры не тратили на него лишнее время. Далее рассмотрим пример, как может выглядеть такой шаблон, из каких блоков может состоять документ. 12 | 13 | 14 | ## I. Заголовок 15 | 16 | **В заголовке** странички с разбором полётов укажите начальную дату и запишите кратко: суть проблемы, сервис и количество часов простоя 17 | 18 | **Проблема:** здесь более подробно опишите проблему, с какими сервисами она произошла, к чему это привело. 19 | 20 | **Основная причина:** здесь укажите основную причину, которая привела к проблеме. 21 | 22 | **Полезные ссылки и инструкции:** подготовьте для шаблона свой список полезных ссылок на внутренние документы и регламенты, чтобы во время работы над инцидентом инженер не тратил время на их поиски. 23 | 24 | ***Пример заполнения области заголовка:*** 25 | 26 | **2020-02-03 — Отказ инфраструктуры сборочных серверов из-за проблем с обновлением, простой ~4 часа** 27 | 28 | **Проблема:** после обновления ОС на сборочных серверах сборочная инфраструктура была недоступна ~4 часа. 29 | 30 | **Основная причина:** служба CI-агента не запустилась после перезагрузки. Обновление было проведено не по регламенту, не согласовано с продуктовыми командами, не был предусмотрен план обновления и отката. 31 | 32 | **Полезные ссылки и инструкции:** 33 | - System Operation Manual — что инженер по инфраструктуре должен сделать в первую очередь (в каждой компании свой регламент). 34 | - Инструкции по снятию типовых показаний и метрик с исследуемых систем (в каждой компании своя специфика и свои метрики для критических показателей). 35 | 36 | 37 | ## II. Хронология проблем и событий 38 | 39 | Тут пишем простую последовательность событий, в свободной форме: что случилось, что произошло, что было сделано инженерами, к чему это привело, прикладываем переписку, логи и тексты оповещений. С сервисных ВМ нужно прикладывать логи аудита и значения метрик ОС. Хронологию проще всего вести в табличной форме. 40 | 41 | ***Пример заполнения хронологии:*** 42 | 43 | **Хронология проблем и событий** 44 | 45 | | N | Дата и время события | Событие или проблема | 46 | | --- | -------------------- | ------------------------------------------------------------------------------- | 47 | | 1 | 2020-06-17 12:00 MSK | Производились работы по обновлению Windows Server на сборочных агентах | 48 | | 2 | 2020-06-17 13:00 MSK | После обновления агенты не запустились из-за проблем с учёткой. Логи приложены. | 49 | | 3 | 2020-06-17 13:30 MSK | Оповестили разработчиков о проблеме. Служебное письмо приложено. | 50 | | 4 | 2020-06-17 13:40 MSK | Начали процедуры отката... | 51 | | ... | 2020-06-17 14:00 MSK | ... прочие действия ... логи ... метрики ... служебная переписка ... | 52 | | N | 2020-06-17 16:00 MSK | Разослали оповещение о восстановлении сборочных пулов агентов. Копия приложена. | 53 | 54 | 55 | ## III. Гипотезы причин возникновения проблем 56 | 57 | Если сходу причины проблем установить не удалось, фиксируются все возможные варианты и последовательно выполняется их проверка. Этот раздел можно изобразить также в виде обычной таблицы. 58 | 59 | ***Пример заполнения таблицы с гипотезами:*** 60 | 61 | **Гипотезы причин возникновения проблем** 62 | 63 | | N | Гипотеза | Подтверждается или опровергнута | Как проверяли гипотезу | 64 | | --- | ------------------------------- | ------------------------------- | ---------------------------------- | 65 | | 1 | Перезатёрлись ключи авторизации | нет | Зашли в админку, проверили ... | 66 | | 2 | Не запустилась служба агента | да | Служба агента - был ручной запуск | 67 | | ... | ... прочие варианты ... | ... | ... | 68 | 69 | 70 | ## IV. План работ 71 | 72 | Тут пишем запланированные виды работ для устранения причин проблемы. Если по какой-то причине её устранение затруднено, также сообщаем об этом. 73 | 74 | ***Пример заполнения плана работ:*** 75 | 76 | **План работ** 77 | 78 | | N | Виды работ для устранения проблемы | Ответственные | Трудности и ограничения | Выполнено | 79 | | --- | ---------------------------------- | ------------- | ------------------------------------- | --------- | 80 | | 1 | Установить сервис на автозапуск | Иванов И.И. | нет | да | 81 | | 2 | Поставить службу на мониторинг | Петров П.П. | нужно настроить item-ы Zabbix-а | нет | 82 | | ... | ... прочие работы ... | Сидоров С.С. | ... | нет | 83 | 84 | 85 | ## V. Возможные улучшения 86 | 87 | В этом разделе описываем по шагам, какие действия нужно предпринять, чтобы избежать этой проблемы в будущем. Это могут быть как технические, так и улучшения существующих регламентов. 88 | 89 | ***Пример заполнения:*** 90 | 91 | **Возможные улучшения** 92 | 93 | 1. В сценарии установки CI-агентов добавить скрипты для автоматического включения сервиса при перезагрузке ОС. 94 | 2. При начальной установке и настройке CI-агента сразу добавлять службу на мониторинг. 95 | 3. Написать регламенты обновления ОС и CI-агентов. 96 | 4. Внести в регламенты работ на инфраструктуре пункт согласования обновлений с продуктовыми командами. 97 | 5. Составить operational manual для задач обновления ОС и CI-агентов, включающий в себя план обновления и отката инфраструктуры. 98 | 6. ... прочие возможные улучшения ... 99 | -------------------------------------------------------------------------------- /plan.md: -------------------------------------------------------------------------------- 1 | # Анализ и планирование работ по долгосрочным задачам 2 | 3 | Простые, типовые задачи обычно не требуют серьёзной аналитики и планирования. Их легче всего вести в трекере. Главное, что требуется по таким задачам — вовремя оповещать заказчиков, когда работы будут выполнены. 4 | 5 | Когда идёт работа по долгосрочным, сложным и непонятным техническим задачам, в которой задействованы инженеры из разных команд, требуется дополнительная координация всех участников, разграничение этапов и зон ответственности. Для этого можно создать, например, общедоступную страничку в Confluence ("на вики"), добавить к ней всех участников, проанализировать задачу и представить этапы работ в таблице. 6 | 7 | Конечно же, отдельные технические задачи нужно по-прежнему вести в командном трекере, но свести вместе всех заинтересованных в решении большой задачи и окинуть взглядом весь процесс проще всего на общей страничке и в табличном виде. 8 | 9 | ## Шаблон плана работ 10 | 11 | Ниже представлен возможный вид странички с планом работ по долгосрочной задаче. Выделенный <в скобках> текст нужно заменить на свои значения. 12 | 13 | ### Общие сведения 14 | 15 | Здесь собираем требования и пожелания от продуктовой команды <название команды> по задаче <краткое описание задачи>. Проведём аналитику и составим план работ. 16 | 17 | - Задача: <ссылка на задачу в трекере, если есть> 18 | - Заказчики (контакты от команды): <ссылки на людей из продуктовой команды, кого можно спрашивать по задаче> 19 | - Исполнители (контакты от DevOps): <кто исполнители или ответственные со стороны DevOps-инженеров> 20 | 21 | ### Краткая суть задачи 22 | 23 | <В свободной форме, со слов заказчика описываем требования, пожелания или ТЗ. Что они хотят получить в конце?> 24 | 25 | ### Анализ требований 26 | 27 | | N | Требование по задаче | Что есть для решения задачи | 28 | |---|----------------------------------------------------------|-----------------------------------------------------------------------------------------| 29 | | 1 | <одна конкретная фича, которая требуется заказчикам> | <Какие инструменты уже есть для решения, а что потребуется разработать/доработать?> | 30 | | 2 | <вторая фича> | <Какие инструменты уже есть для решения, а что потребуется разработать/доработать?> | 31 | | 3 | <третья фича> | <Какие инструменты уже есть для решения, а что потребуется разработать/доработать?> | 32 | | 4 | ... | ... | 33 | | 5 | ... | ... | 34 | 35 | ### План работ 36 | 37 | | N | Этапы работ | Планируемые объемы работ | Фактические объёмы | Планируемый ввод в эксплуатацию | Статус | Ответственный за реализацию от DevOps | Координатор со стороны заказчика | Ограничения или возможные проблемы. Комментарии | 38 | |---|-----------------------------------|--------------------------|----------------------|---------------------------------|-------------|---------------------------------------|-------------------------------------------|------------------------------------------------------------------------------| 39 | | 1 | Анализ требований | <трудочасы по плану> | <трудочасы по факту> | <дата или месяц сдачи этапа> | <Решено> | <исполнители от DevOps> | <Кто будет проверять и принимать работу?> | ... | 40 | | 3 | <отдельный логический этап работ> | <трудочасы по плану> | <трудочасы по факту> | <дата или месяц сдачи этапа> | <Не готово> | <исполнители от DevOps> | <Кто будет проверять и принимать работу?> | <Возникшие проблемы или ограничения для реализации этапа. Любые комментарии> | 41 | | 2 | <отдельный логический этап работ> | <трудочасы по плану> | <трудочасы по факту> | <дата или месяц сдачи этапа> | <В работе> | <исполнители от DevOps> | <Кто будет проверять и принимать работу?> | <Возникшие проблемы или ограничения для реализации этапа. Любые комментарии> | 42 | | 4 | <отдельный логический этап работ> | <трудочасы по плану> | <трудочасы по факту> | <дата или месяц сдачи этапа> | <Решено> | <исполнители от DevOps> | <Кто будет проверять и принимать работу?> | ... | 43 | | 5 | <отдельный логический этап работ> | <трудочасы по плану> | <трудочасы по факту> | <дата или месяц сдачи этапа> | <Решено> | <исполнители от DevOps> | <Кто будет проверять и принимать работу?> | ... | 44 | | 6 | ... | ... | ... | ... | ... | ... | ... | ... | 45 | | 7 | ... | ... | ... | ... | ... | ... | ... | ... | 46 | | 8 | ... | ... | ... | ... | ... | ... | ... | ... | 47 | | 9 | ... | ... | ... | ... | ... | ... | ... | ... | 48 | -------------------------------------------------------------------------------- /tech-articles.md: -------------------------------------------------------------------------------- 1 | # Содержание коротких технических статей 2 | 3 | Инженерам иногда приходится писать инструкции, короткие технические статьи, готовить рассказы для презентаций и воркшопов, с объяснением того или иного рекомендуемого решения. При подготовке таких рассказов и статей сразу возникают вопросы: о чем писать, сколько писать, что рассказать, а что опустить. 4 | 5 | У профессиональных писателей и редакторов есть шаблоны и заготовки текстов на различные темы. Попробуем собрать здесь ссылки на лучшие рекомендации в помощь тем, кто пишет технические статьи или рассказы. 6 | 7 | 8 | ## Возможная структура "идеального" технического рассказа для воркшопа или статьи 9 | 10 | Конечно же ничего идеального не бывает, кроме "золотого сечения" и числа π :) Но следующие рекомендации могут вам пригодиться как для подготовки каркаса для технической статьи, так и для рассказа на воркшопе или вебинаре. 11 | 12 | Каким может быть каркас (структура) технической статьи или рассказа: 13 | 1. Технические проблемы, которые будут разобраны или решены в статье (или в рассказе на воркшопе). 14 | 2. Выбранные для решения инструменты, технологии или методики. На что опирались при выборе способов решения, какие метрики и целевые показатели для оценки итогов решения выбирали. 15 | 3. Описание того, как внедряли инструмент или реализовывали техническое решение. Расскажите о процессе решения, разработки инструмента, использовании технологии или методики. 16 | 4. Итоги внедрения: к чему пришли, оценка значений метрик и какая экономия получена. 17 | 5. Описание того, какие выявлены ограничения инструмента, технологии или методики в процессе решения. 18 | 6. Предложения, как можно улучшить и доработать предлагаемое решение в будущем. 19 | 7. Выводы, краткое резюме и основные мысли статьи или рассказа. 20 | 21 | Приведём также один пример готовой структуры для написания вообще любой статьи ([взято отсюда](https://doitinbound.com/blog/posts-guides/)). Как пишет сам автор: "По ней можно написать пост, даже если вы считаете, что не умеете писать" :) 22 | 23 | ![article-structure](http://doitinbound.com/wp-content/uploads/2018/04/post-guides.png) 24 | 25 | 26 | ## Полезные ссылки для подготовки технических статей, воркшопов и рассказов. Советы и сервисы 27 | 28 | **Сервисы:** 29 | 1. Сервис Главред: [проверит стилистику и грамотность текста](https://glvrd.ru/). 30 | 2. The Rules: "[Правила русского языка. Проверка орфографии и пунктуации](https://therules.ru/)". 31 | 32 | **Советы:** 33 | 1. Как начать писать лучше? Главред: [Советы и статьи о тексте, редактуре, информационном стиле и рекламе](https://soviet.glvrd.ru/) (см. раздел для начинающих). 34 | 2. Конечно же "[Новые правила деловой переписки](https://letters.glvrd.ru/)" 35 | 3. Рекомендации по подготовке презентаций и как готовиться к докладу: "[Точка контакта: презентация](https://bizikov.ru/books/tochka-kontakta-prezentaciya/)". 36 | 4. DO IT INBOUND: "[Готовая структура для разных типов статей](https://doitinbound.com/blog/posts-guides/)" 37 | 5. "[Как написать простое и понятное объявление](http://public-notice.ru/)". 38 | 6. Бюро: "[Почему НЕ НАДО ПИСАТЬ КАПСОМ](https://bureau.ru/bb/soviet/20181104/)" и как лучше. 39 | -------------------------------------------------------------------------------- /techmap.md: -------------------------------------------------------------------------------- 1 | # Технологическая карта производственного процесса 2 | 3 | Более подробно про то, как мы пришли к пониманию необходимости использования технологической карты в DevOps процессах, можно почитать в статье на Хабре: "[Управление хаосом: наводим порядок с помощью технологической карты](https://habr.com/ru/company/pt/blog/480754/)" 4 | 5 | ## Типовые задачи, производственные этапы, производственная технологическая цепочка 6 | 7 | В работе DevOps-инженеров быстро накапливается множество однотипных и рутинных операций. От заказчиков в основном приходят так называемые **типовые инженерные задачи**, решение которых уже автоматизировано полностью или частично, не вызывает трудностей у исполнителей и не требует значительных объемов работ. Вы можете сами проанализировать такие задачи и выделить отдельные категории работ, или **производственные этапы**, этапы разбить на неделимые логические шаги, а из нескольких этапов получится **производственная технологическая цепочка**. 8 | 9 | ![](./.media/typical_steps.png) 10 | 11 | Простейший пример технологической цепочки — это этапы сборки, деплоя и тестирования каждого продукта компании. В свою очередь этап сборки может состоять из множества отдельных типовых шагов: выкачивание исходников из хранилища кода, скачивание и подготовка зависимостей и 3rd-party библиотек, юнит-тестирование и статический анализ кода, выполнение сборочного сценария, публикация артефактов в некоторое хранилище и, например, генерация релиз-нотов. 12 | 13 | ## Классификация этапов 14 | 15 | Начинать анализ любого рабочего процесса необходимо с классификации и детализации типовых шагов производственного конвейера. В каждой компании разработчике ПО обычно уже есть своя сложившаяся технологическая цепочка. Также в реальной разработке есть еще и вспомогательные этапы: мониторинг, сертификация продуктов, автоматизация рабочих процессов и другие. 16 | 17 | Если взять все этапы и шаги, попытаться закодировать их тегами и развернуть в одну цепочку, то она получится очень длинной и непонятной, как «хвост питона». Вот пример тегов этапов из реального процесса: 18 | 19 | ```text 20 | [Production] — [InfMonitoring] — [SourceCodeControl] — [Prepare] — [PrepareLinuxDocker] — [PrepareWinDocker] — [Build] — [PullSourceCode] — [PrepareDep] — [UnitTest] — [CodeCoverage] — [StaticAnalyze] — [BuildScenario] — [PushToSnapshot] — [ChangelogBuilder] — [Deploy] — [PrepareTestStand] — [PullTestCode] — [PrepareTestEnv] — [PullArtifact] — [DeployArtifact] — [Test] — [BVTTest] — [SmokeTest] — [FuncTest] — [LoadTest] — [IntegrityTest] — [DeliveryTest] — [MonitoringStands] — [TestManagement] — [Promote] — [QualityTag] — [MoveToRelease] — [License] — [Publish] — [PublishGUSFLUS] — [ControlVisibility] — [Install] — [LicenseActivation] — [RequestUpdates] — [PullUpdates] — [InitUpdates] — [PrepareEnv] — [InstallUpdates] — [Telemetry] — [Workflow] — [Communication] — [Certification] — [CISelfSufficiency] 21 | ``` 22 | 23 | Это этапы сборки продуктов [Build], их деплоя на тестовые серверы [Deploy], тестирования [Test], продвижения сборок в релизные репозитории по итогам тестирования [Promote], генерации и публикации лицензий [License], публикации [Publish] на сервере обновлений и доставка с них до инфраструктуры заказчиков, инсталляция и обновление компонентов продуктов на инфраструктуре заказчика средствами Product Configuration Management [Install], а также сбор телеметрии [Telemetry] с установленных продуктов. 24 | 25 | Кроме них можно выделить отдельные этапы: мониторинга состояния инфраструктуры [InfMonitoring], управления версиями исходного кода [SourceCodeControl], подготовки сборочного окружения [Prepare], управления проектами [Workflow], обеспечения команд средствами коммуникации [Communication], сертификации продуктов [Certification] и обеспечения самодостаточности CI-процессов [CISelfSufficiency] (например, независимости сборок от интернета). 26 | 27 | Десятки отдельных шагов можно даже не рассматривать, потому что они могут быть очень специфичными для каждой компании. 28 | 29 | ## Технологическая карта 30 | 31 | Будет гораздо легче понять и окинуть взглядом весь производственный процесс, если представить его в виде так называемой **технологической карты**. Это таблица, в которую по строкам записаны отдельные производственные этапы и декомпозированные шаги, а по столбцам — описание того, что делается на каждом этапе или шаге. Основной акцент стоит сделать на ресурсах, обеспечивающих каждый этап, и разграничении зон ответственности. 32 | 33 | Карта — это своеобразный классификатор. Она отражает крупные технологические части производства продуктов. С помощью неё команде DevOps-инженеров будет легче взаимодействовать с разработчиками и совместно планировать внедрение новых этапов автоматизации, а также понимать, какие трудозатраты и ресурсы (человеческие и «железные») для этого потребуются. 34 | 35 | Более коротко, технологическая карта — это обобщенная картина производственного процесса, где отражены четко классифицированные блоки с типовой функциональностью. **Самое главное: карта позволяет увидеть весь процесс целиком, крупными кусками с возможностью их детализации.** 36 | 37 | В каждой компании карта может выглядеть по своему. Например, вот так: 38 | 39 | ![](./.media/tech-map.png) 40 | 41 | ### Структура технологической карты 42 | 43 | Карта состоит из нескольких основных частей: 44 | 45 | 1. Область заголовков — здесь находится общее описание карты, вводятся базовые понятия, определяются основные ресурсы и результаты производственного процесса. 46 | 2. Область общей информации — здесь можно управлять отображением данных по отдельным продуктам, привести сводку и статистику по реализованным этапам и шагам в целом по всем продуктам. 47 | 3. Технологическая карта — табличное описание технологического процесса. На самой карте: 48 | * приводятся все этапы, шаги и их коды; 49 | * даются краткое и полное описания этапов; 50 | * указываются входные ресурсы и сервисы, используемые на каждом этапе; 51 | * указываются результаты каждого этапа и отдельного шага; 52 | * указывается зона ответственности по каждому этапу и шагу; 53 | * определяются технические ресурсы, например HDD (SSD), RAM, vCPU, и человеко-часы, необходимые для поддержки работ на данном этапе, как на текущий момент — факт, так и в будущем — план; 54 | * в ячейках карты для каждого продукта указывается, какие технологические этапы или шаги для него реализованы, планируются к внедрению, неактуальны или не реализованы. 55 | 56 | ### Шаблон описания производственного этапа или шага 57 | 58 | Чтобы не усложнять технологическую карту, более подробное описание каждого этапа или шага производственного конвейера можно вынести в отдельные стандартизированные карточки. Выглядеть эти карточки могут так: 59 | 60 | | Элемент технологического конвейера | Описание характеристики | 61 | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 62 | | Название или ключ: | Любое обозначение в виде [тега] | 63 | | Тип (этап или шаг): | — / этап / шаг | 64 | | Вид работы: | Короткое, в пару слов, описание видов работ выполняемых на этапе или шаге. | 65 | | Краткое описание: | Короткий дайджест того, что происходит на данном этапе или шаге. | 66 | | Подробное описание: | Подробное и детализированное описание этапа или шага технологического конвейера. | 67 | | Входные ресурсы: | Какими ресурсами обеспечен данный этап или шаг, что требуется на входе для возможности его полной реализации? | 68 | | Результаты: | Что получаем по итогу выполнения работ на данном этапе или шаге? | 69 | | Зона ответственности и контакты: | Контакты ответственных за реализацию данного этапа или шага. | 70 | | Ссылки на корп. стандарт: | Ссылки на инструкции и описания, скрипты реализации или стандартные инструменты, рекомендуемые DevOps-инженерами компании. Исполнителям должно быть понятно, по каким стандартам нужно реализовывать тот или иной этап и шаг. | 71 | 72 | ### Шаблон технологической карты 73 | 74 | Табличку для техкарты можно создать в любом удобном для вас инструменте. Например, на скриншоте выше представлена карта, которую мы генерим для себя автоматически, в виде веб-странички (HTML + JS + CSS). Но для простоты можно использовать Excel-таблицы, этого вполне достаточно и более понятно большинству коллег. 75 | 76 | Вы можете скачать пример технологической карты в Excel по ссылке: [TechnologicalMapExample.xlsx](./.media/TechnologicalMapExample.xlsx). Данные по продуктам приведены в таблице только для примера. Если решите ей воспользоваться, вам нужно будет провести собственную аналитику по вашим продуктам и заполнить ячейки актуальными данными. 77 | 78 | ![](./.media/tech-map-excel.png) 79 | 80 | ### Принятие решений на основе технологической карты 81 | 82 | Изучив карту, возможно предпринять некоторые действия — в зависимости от роли сотрудника в компании (руководитель разработки, менеджер продукта, разработчик или тестировщик): 83 | 84 | * понять, какие этапы отсутствуют в реальном продукте или проекте, и оценить необходимость их внедрения; 85 | * разграничить зоны ответственности между несколькими отделами, если они работают над разными этапами; 86 | * договориться о контрактах на входах и выходах этапов; 87 | * интегрировать свой этап работ в общий процесс разработки; 88 | * точнее оценить потребность в ресурсах, обеспечивающих каждый из этапов. 89 | 90 | ## Резюмируя все вышесказанное 91 | 92 | Технологическая карта универсальна, расширяема и легко поддерживается. Разрабатывать и сопровождать описание процессов в таком виде гораздо легче, чем в любых других процессных моделях. Кроме того, табличное описание проще для человека, привычней и лучше структурировано, чем, например, функциональная модель. --------------------------------------------------------------------------------