Когда в IT-компании работают 6 человек, которые пилят одну систему и обсуждают её в кулуарах, описание системы и документация кажутся ненужными. Но когда систем уже более 100, без описания не обойтись. Ведь непродуманное изменение UI может остановить создание заказов. Мы создали единый шаблон описания системы, чтобы документация стала максимально полезной.
Меня зовут Александра Камзеева, я работаю системным аналитиком уже 9 лет, из них 3.5 года в Lamoda. Я много читаю, анализирую текущую документацию и создаю новую. В работе я всегда структурирую информацию и делаю её максимально удобной.
Плюсы хорошего описания системы таковы:
Мы сделали шаблон для такого описания, который может использовать любая команда. В этой статье я расскажу на примерах, что подтолкнуло нас к созданию шаблона описания системы, историю создания и как его используют сейчас в Lamoda.
Для начала я опишу свое понимание шаблона. Давайте представим, что мне надо найти маленькую машинку в неприбранной комнате. Не факт, что я справлюсь. Зато могу случайно наступить на детальку Лего.
А теперь представим, что все игрушки разложены по своим местам и отсортированы. Я заранее вижу, в каком ящике лежат все машинки, найду нужную быстрее, проще и не буду тратить нервы на это.
Аналогично с документацией. Шаблон – и есть такой порядок. Мы сделали основу для описания системы, которую может использовать любая команда.
В Lamoda есть более 100 систем, которые автоматизируют доставку заказов, контакт-центр, склад, фотостудию, другие операционные и бизнес-процессы. Разработкой и поддержкой занимаются больше 300 инженеров. Любому из них может понадобиться описание любой из этих 100 систем.
Каждая команда самостоятельно описывает свою систему в отдельном спейсе в Confluence. В документировании обязательно участвует техлид, потому что он обязан фиксировать информацию. Также систему описывают активные тестировщики и разработчики, которым жалко просто так потерять полученные знания. И естественно, аналитики, поскольку документация – один из наших главных инструментов.
Может показаться, что эта свобода приводит к хаосу. Но это не так, потому что у нас есть культура компании: ответственное отношение к документации, открытый шаринг знаний, привычка фиксировать артефакты проекта и системы. Эта традиция сложилась отчасти благодаря неуспешным проектам. Инциденты доказали командам разработки, насколько важно документировать процессы и функциональность системы.
Ниже я расскажу несколько случаев, когда запутанная документация или ее отсутствие приводили к проблемам.
Просто добавь две кнопки
Первая проблема, которая подтолкнула нас к созданию шаблона – у нас не было описания некоторых систем, что приводило к сбоям и доработкам.
У нас был проект Self Order Management (SOM). Мы решили добавить в личный кабинет клиента две кнопки: «Перенос даты доставки» и «Отмена заказа». До этого клиент мог отменить или перенести заказ только звонком в контакт-центр. Понятно, что у некоторых покупателей не было времени или желания общаться с оператором. В итоге торговый представитель мог привезти ненужный заказ или не застать клиента дома. В таких случаях Lamoda несет издержки. Проект был нужный и важный.
Казалось бы, добавить две кнопочки! На самом деле, за ними скрывалось много логики в четырех системах. Изменение заказа проходит через систему процессинга – огромный монолит, где можно тронуть что-то в одном месте, а выстрелит в другом. К сожалению, тонкости её работы не были описаны в документации, на это не обратили внимания во время проектирования проекта. После релиза кнопки работали не так, как ожидалось, и его откатили обратно. В итоге вместо двух человеко-месяцев на этот проект ушло полгода.
Конечно, мы получили такой результат не только из-за отсутствия документации. Но если бы у нас существовало понятное описание процессов отмены и переноса заказа, то, возможно, исход был бы другим.
Сложный онбординг
Вторая проблема, которая подвела нас к созданию шаблона – это сложности онбординга. Я пришла работать в команду, которая занималась системой процессинга заказов. Для погружения я читала документацию в спейсе системы и в трех разделах обнаружила три разных описания основной сущности нашей системы – статуса заказа.
В этом случае не получилось сделать онбординг легче. Такая документация не помогала передать знания коллегам, которые не сталкивались с нашей системой ранее.
Проблема чистого листа
Третья предпосылка к созданию шаблона – проблема чистого листа. Для каждой новой системы техлид должен сделать с нуля соответствующий спейс. Техлид думает, какие разделы стоит завести. До создания шаблона сотрудник изучал другие спейсы и смотрел, какие разделы используются и будут полезными для его системы. Раньше на это уходило много времени.
Каждую неделю системные аналитики проводят стендап и обсуждают вопросы, которые встречаются на проектах и не только. И не раз коллеги жаловались, как сложно найти информацию и разобраться в спейсах различных систем. Поскольку у нас постоянно пригорало из-за этого, мы решили взять в свои руки описание систем, к которым мы прикреплены. А дальше будет видно, что делать.
Сначала мы определили признаки хорошего шаблона:
Далее проанализировали текущее описание разных систем и выявили часто встречающиеся разделы:
В разделе проектов и фич лежали спецификации для разработки проектов. В разделах Development и QA находилась специфическая информация для разработки и тестировщиков. В разделе инцидентов были описаны происшествия, которые возникали в системе, и их решения.
Мы поделились идеей шаблона с другими коллегами на неформальных встречах (обеды на кухне, стенд-апы, команды-соседи, с которыми периодически разговариваешь) и создали рабочую группу добровольцев. Ими были представители разных компетенций: два менеджера, три техлида и два тестировщика. Они добавили в шаблон следующие разделы:
Далее мы проверили шаблон описания систем с коллегами с широкой компетенцией: руководителями IT-подразделений, опытными техлидами и тестлидами больших интеграционных проектов. В итоге они добавили еще немного полезных разделов:
Полученный документ мы проверили на наше определение хорошего шаблона в Lamoda:
Мы сделали хороший шаблон, подходящий для описания систем Lamoda. Надеюсь, он будет полезен и другим компаниям. Особенно хочу выделить следующие три раздела:
Описание основных процессов системы. Да, кажется очевидным, что этот раздел нужен. Но почему-то он не всегда существует, как было у нас на примере с кнопочками отмены и переноса заказа. Если бы мы заранее описали процессы отмены и переноса заказа, уменьшился бы риск провала проекта.
Чек-листы – раздел, который напоминает о самом важном в регулярном процессе. Например, у нас есть “Чек-лист подключения нового метода оплаты” в описании системы управления методами оплаты. Там прописано, что мы должны согласовывать добавление или изменение метода оплаты с бухгалтерией, с контакт-центром, с доставкой и с другими бизнес-подразделениями.
Однажды мы забыли сообщить контакт-центру об изменениях метода оплаты. И когда клиент позвонил в наш контакт-центр и спросил об этом, оператор ничего не смог сказать. Это привело к конфликту между контакт-центром и командой разработки, отвечающей за методы оплаты. После этого случая мы заводим чек-листы для ключевых запусков проектов, подключения новых партнеров и т.д.
Домашняя страница спейса – раздел с информацией о том, зачем эта система нужна, о составе команды и стейкхолдере. Мы должны согласовывать изменения систем и ресурсы на разработку со стейкхолдером. Поэтому здорово, когда эту информацию можно получить, просто заглянув в Confluence.
Тут же мы указываем информацию о составе команды, чтобы понимать, к кому обратиться с вопросами о системе. Это помогает и новичкам с распухшей головой. Здорово, когда новый сотрудник может подглядеть, с кем он только что разговаривал, кто этот человек, какая у него роль и как его зовут.
В первую кучку мы отправили всё неактуальное и ненужное. Эти страницы мы удаляли или отправляли в архив.
Вторая кучка – это нужное, но неактуальное. Мы помечали страницы как неактуальные, заводили задачу в Jira и дальше актуализировали эту информацию в соответствии с нашим бэклогом.
Третья кучка самая простая. Когда все понятно, разделы актуальные – мы просто переносили их в нужное место.
До этих встреч по всему спейсу были хаотично разбросаны описания процессов и архитектуры, записки тестировщиков и разработчиков, инциденты. Также не было домашней страницы.
За 6 часов встреч мы получили отличный результат. Из хаоса у нас образовались структура и порядок. Теперь в ней можно понять, где найти описание процессов, информацию об архитектуре и об инцидентах. И что немаловажно, у нас появилась домашняя страница. Здесь было написано, зачем нужна система процессинга заказа и кто её стейкхолдер.
Наша большая система участвует почти во всех бизнес-направлениях. Но собственного стейкхолдера у нас раньше не было. Пока мы делали home page, обсудили с CTO, с кем согласовывать изменения системы. Таким образом, определился коллега, который приоритезировал доработки. Теперь это выглядит забавным фактом, что создание домашней страницы привело к появлению стейкхолдера.
Похожие результаты по использованию шаблона получили другие аналитики, которые внедряли его в своих направлениях. Таким образом, мы покрыли большую часть систем, которые принимали активное участие во многих интеграционных проектах.
У нас были команды, чьи системы часто были задействованы в интеграционных проектах, но описания о них не хватало. Там обычно чувствовалась необходимость в документации, поэтому продавать идею не пришлось.
Мы показывали успешный опыт применения шаблонов техлидам и менеджерам таких команд. Некоторые команды на основе нашего примера самостоятельно приводили в порядок свою документацию, другие просили помощи аналитиков.
Наш шаблон не является принудительным или обязательным описанием системы. Коллеги берут шаблон за основу, если у них есть в нем потребность, и редактируют под свои нужды. Например, выносят обмены из подраздела в раздел, если система в основном состоит из них.
Все наши системы отличаются в описании, но общая структура и общая логика все равно сохраняются. Теперь мы легче находим информацию о том, из каких процессов состоит система, об архитектуре системы и так далее.
Мы в Lamoda любим обмениваться знаниями. У нас есть большие интеграционные проекты, которые мотивируют на это. Мы высылаем ссылки на актуальное описание систем, и коллеги получают нужную информацию без дополнительных вопросов и так загруженным техлидам.
Спустя 2 года после создания шаблона я опросила коллег и получила у большинства хорошую обратную связь. Они используют шаблон, редактируя структуру так, как им нужно.
Но есть и люди, считающие, что нам не нужна документация и шаблон. В основном, так рассуждают команды тех систем, в которых сейчас нет острой необходимости что-то документировать.
Они работают над системами, которые почти не изменяются: нет интеграционных проектов, нет необходимости рассказывать про эти системы другим коллегам, соответственно, нет желания документировать.
Я думаю, перед началом большого проекта наша культура и набитые шишки напомнят о необходимости документировать основные процессы, и они поменяют мнение.
Меня зовут Александра Камзеева, я работаю системным аналитиком уже 9 лет, из них 3.5 года в Lamoda. Я много читаю, анализирую текущую документацию и создаю новую. В работе я всегда структурирую информацию и делаю её максимально удобной.
Плюсы хорошего описания системы таковы:
- помогает найти нужную информацию быстрее и проще, чем в неструктурированном описании;
- уменьшает риск неуспешности проектов;
- облегчает онбординг сотрудников.
Мы сделали шаблон для такого описания, который может использовать любая команда. В этой статье я расскажу на примерах, что подтолкнуло нас к созданию шаблона описания системы, историю создания и как его используют сейчас в Lamoda.
Что такое шаблон и зачем он нужен
Для начала я опишу свое понимание шаблона. Давайте представим, что мне надо найти маленькую машинку в неприбранной комнате. Не факт, что я справлюсь. Зато могу случайно наступить на детальку Лего.
А теперь представим, что все игрушки разложены по своим местам и отсортированы. Я заранее вижу, в каком ящике лежат все машинки, найду нужную быстрее, проще и не буду тратить нервы на это.
Аналогично с документацией. Шаблон – и есть такой порядок. Мы сделали основу для описания системы, которую может использовать любая команда.
В каких условиях мы работаем с документацией
В Lamoda есть более 100 систем, которые автоматизируют доставку заказов, контакт-центр, склад, фотостудию, другие операционные и бизнес-процессы. Разработкой и поддержкой занимаются больше 300 инженеров. Любому из них может понадобиться описание любой из этих 100 систем.
Каждая команда самостоятельно описывает свою систему в отдельном спейсе в Confluence. В документировании обязательно участвует техлид, потому что он обязан фиксировать информацию. Также систему описывают активные тестировщики и разработчики, которым жалко просто так потерять полученные знания. И естественно, аналитики, поскольку документация – один из наших главных инструментов.
Может показаться, что эта свобода приводит к хаосу. Но это не так, потому что у нас есть культура компании: ответственное отношение к документации, открытый шаринг знаний, привычка фиксировать артефакты проекта и системы. Эта традиция сложилась отчасти благодаря неуспешным проектам. Инциденты доказали командам разработки, насколько важно документировать процессы и функциональность системы.
Ниже я расскажу несколько случаев, когда запутанная документация или ее отсутствие приводили к проблемам.
Просто добавь две кнопки
Первая проблема, которая подтолкнула нас к созданию шаблона – у нас не было описания некоторых систем, что приводило к сбоям и доработкам.
У нас был проект Self Order Management (SOM). Мы решили добавить в личный кабинет клиента две кнопки: «Перенос даты доставки» и «Отмена заказа». До этого клиент мог отменить или перенести заказ только звонком в контакт-центр. Понятно, что у некоторых покупателей не было времени или желания общаться с оператором. В итоге торговый представитель мог привезти ненужный заказ или не застать клиента дома. В таких случаях Lamoda несет издержки. Проект был нужный и важный.
Казалось бы, добавить две кнопочки! На самом деле, за ними скрывалось много логики в четырех системах. Изменение заказа проходит через систему процессинга – огромный монолит, где можно тронуть что-то в одном месте, а выстрелит в другом. К сожалению, тонкости её работы не были описаны в документации, на это не обратили внимания во время проектирования проекта. После релиза кнопки работали не так, как ожидалось, и его откатили обратно. В итоге вместо двух человеко-месяцев на этот проект ушло полгода.
Конечно, мы получили такой результат не только из-за отсутствия документации. Но если бы у нас существовало понятное описание процессов отмены и переноса заказа, то, возможно, исход был бы другим.
Сложный онбординг
Вторая проблема, которая подвела нас к созданию шаблона – это сложности онбординга. Я пришла работать в команду, которая занималась системой процессинга заказов. Для погружения я читала документацию в спейсе системы и в трех разделах обнаружила три разных описания основной сущности нашей системы – статуса заказа.
В этом случае не получилось сделать онбординг легче. Такая документация не помогала передать знания коллегам, которые не сталкивались с нашей системой ранее.
Проблема чистого листа
Третья предпосылка к созданию шаблона – проблема чистого листа. Для каждой новой системы техлид должен сделать с нуля соответствующий спейс. Техлид думает, какие разделы стоит завести. До создания шаблона сотрудник изучал другие спейсы и смотрел, какие разделы используются и будут полезными для его системы. Раньше на это уходило много времени.
Как мы создавали шаблон и что получилось
Каждую неделю системные аналитики проводят стендап и обсуждают вопросы, которые встречаются на проектах и не только. И не раз коллеги жаловались, как сложно найти информацию и разобраться в спейсах различных систем. Поскольку у нас постоянно пригорало из-за этого, мы решили взять в свои руки описание систем, к которым мы прикреплены. А дальше будет видно, что делать.
Сначала мы определили признаки хорошего шаблона:
- Хороший шаблон помогает найти нужную информацию быстрее и легче за счет структуры описания системы.
- Информация в системе не дублируется. Конечно, это достигается не только документом, но и культурой ведения документации. В шаблоне можно заложить атомарность разделов, чтобы ссылаться на них. Это не даст лишний повод для дублирования информации.
- Хороший шаблон применим к большинству систем. Да, он скорее всего будет избыточен для отдельной системы, но так он может покрыть если не все кейсы, то большинство.
- Он помогает сохранить всё нужное и напоминает о важном.
Далее проанализировали текущее описание разных систем и выявили часто встречающиеся разделы:
В разделе проектов и фич лежали спецификации для разработки проектов. В разделах Development и QA находилась специфическая информация для разработки и тестировщиков. В разделе инцидентов были описаны происшествия, которые возникали в системе, и их решения.
Мы поделились идеей шаблона с другими коллегами на неформальных встречах (обеды на кухне, стенд-апы, команды-соседи, с которыми периодически разговариваешь) и создали рабочую группу добровольцев. Ими были представители разных компетенций: два менеджера, три техлида и два тестировщика. Они добавили в шаблон следующие разделы:
Далее мы проверили шаблон описания систем с коллегами с широкой компетенцией: руководителями IT-подразделений, опытными техлидами и тестлидами больших интеграционных проектов. В итоге они добавили еще немного полезных разделов:
Проверяем качество шаблона
Полученный документ мы проверили на наше определение хорошего шаблона в Lamoda:
- Он помогает найти нужную информацию быстрее и легче. У нас получилась удобная структура: я двигаюсь по дереву и понимаю, что и где находится. Если нужна информация о процессах системы (например, отмена заказа), значит, иду в “Описание основных процессов”.
- Информация о системе не дублируется благодаря атомарности разделов. Например, можно описать печатные формы в одном разделе, а затем ссылаться на него из раздела “Описание основных процессов”, чтобы информация не повторялась.
- Хороший шаблон применим к большинству систем. Наш шаблон учитывает разделы для всех систем Lamoda, поэтому структура описания адаптирована под каждую систему. Например, система процессинга заказов не использует описание пользовательских интерфейсов или ссылки на исследования АВ-тестирования. А для сайта — это два ключевых раздела.
- Хороший шаблон помогает ничего не забыть. Об этом я расскажу подробнее в следующий главе.
Самые полезные разделы шаблона
Мы сделали хороший шаблон, подходящий для описания систем Lamoda. Надеюсь, он будет полезен и другим компаниям. Особенно хочу выделить следующие три раздела:
Описание основных процессов системы. Да, кажется очевидным, что этот раздел нужен. Но почему-то он не всегда существует, как было у нас на примере с кнопочками отмены и переноса заказа. Если бы мы заранее описали процессы отмены и переноса заказа, уменьшился бы риск провала проекта.
Чек-листы – раздел, который напоминает о самом важном в регулярном процессе. Например, у нас есть “Чек-лист подключения нового метода оплаты” в описании системы управления методами оплаты. Там прописано, что мы должны согласовывать добавление или изменение метода оплаты с бухгалтерией, с контакт-центром, с доставкой и с другими бизнес-подразделениями.
Однажды мы забыли сообщить контакт-центру об изменениях метода оплаты. И когда клиент позвонил в наш контакт-центр и спросил об этом, оператор ничего не смог сказать. Это привело к конфликту между контакт-центром и командой разработки, отвечающей за методы оплаты. После этого случая мы заводим чек-листы для ключевых запусков проектов, подключения новых партнеров и т.д.
Домашняя страница спейса – раздел с информацией о том, зачем эта система нужна, о составе команды и стейкхолдере. Мы должны согласовывать изменения систем и ресурсы на разработку со стейкхолдером. Поэтому здорово, когда эту информацию можно получить, просто заглянув в Confluence.
Тут же мы указываем информацию о составе команды, чтобы понимать, к кому обратиться с вопросами о системе. Это помогает и новичкам с распухшей головой. Здорово, когда новый сотрудник может подглядеть, с кем он только что разговаривал, кто этот человек, какая у него роль и как его зовут.
Как я начала использовать шаблон в своей системе
- Прежде всего, я создала нужные разделы шаблона без наполнения. Это было легко и заняло не более 30 минут.
- Дальше было самое сложное: мы поставили регулярные встречи с техлидом, на которых мы начали разбор документации нашей системы. На первой встрече мы распределили текущие страницы по трем кучкам.
В первую кучку мы отправили всё неактуальное и ненужное. Эти страницы мы удаляли или отправляли в архив.
Вторая кучка – это нужное, но неактуальное. Мы помечали страницы как неактуальные, заводили задачу в Jira и дальше актуализировали эту информацию в соответствии с нашим бэклогом.
Третья кучка самая простая. Когда все понятно, разделы актуальные – мы просто переносили их в нужное место.
До этих встреч по всему спейсу были хаотично разбросаны описания процессов и архитектуры, записки тестировщиков и разработчиков, инциденты. Также не было домашней страницы.
За 6 часов встреч мы получили отличный результат. Из хаоса у нас образовались структура и порядок. Теперь в ней можно понять, где найти описание процессов, информацию об архитектуре и об инцидентах. И что немаловажно, у нас появилась домашняя страница. Здесь было написано, зачем нужна система процессинга заказа и кто её стейкхолдер.
Наша большая система участвует почти во всех бизнес-направлениях. Но собственного стейкхолдера у нас раньше не было. Пока мы делали home page, обсудили с CTO, с кем согласовывать изменения системы. Таким образом, определился коллега, который приоритезировал доработки. Теперь это выглядит забавным фактом, что создание домашней страницы привело к появлению стейкхолдера.
Как мы распространяли шаблон
Похожие результаты по использованию шаблона получили другие аналитики, которые внедряли его в своих направлениях. Таким образом, мы покрыли большую часть систем, которые принимали активное участие во многих интеграционных проектах.
У нас были команды, чьи системы часто были задействованы в интеграционных проектах, но описания о них не хватало. Там обычно чувствовалась необходимость в документации, поэтому продавать идею не пришлось.
Мы показывали успешный опыт применения шаблонов техлидам и менеджерам таких команд. Некоторые команды на основе нашего примера самостоятельно приводили в порядок свою документацию, другие просили помощи аналитиков.
Обратная связь о шаблоне
Наш шаблон не является принудительным или обязательным описанием системы. Коллеги берут шаблон за основу, если у них есть в нем потребность, и редактируют под свои нужды. Например, выносят обмены из подраздела в раздел, если система в основном состоит из них.
Все наши системы отличаются в описании, но общая структура и общая логика все равно сохраняются. Теперь мы легче находим информацию о том, из каких процессов состоит система, об архитектуре системы и так далее.
Мы в Lamoda любим обмениваться знаниями. У нас есть большие интеграционные проекты, которые мотивируют на это. Мы высылаем ссылки на актуальное описание систем, и коллеги получают нужную информацию без дополнительных вопросов и так загруженным техлидам.
Спустя 2 года после создания шаблона я опросила коллег и получила у большинства хорошую обратную связь. Они используют шаблон, редактируя структуру так, как им нужно.
Но есть и люди, считающие, что нам не нужна документация и шаблон. В основном, так рассуждают команды тех систем, в которых сейчас нет острой необходимости что-то документировать.
Они работают над системами, которые почти не изменяются: нет интеграционных проектов, нет необходимости рассказывать про эти системы другим коллегам, соответственно, нет желания документировать.
Я думаю, перед началом большого проекта наша культура и набитые шишки напомнят о необходимости документировать основные процессы, и они поменяют мнение.
Советы себе и желающим повторить наш путь
- Мы систематизируем знания о системе, отвечая на вопросы, без какой информации плохо, что указать в первую очередь, какие данные будут самыми популярными. Благодаря этому, расставляем приоритеты и избегаем бесполезных описаний.
- Стараемся избегать дублирования информации. Совет очевидный, но все равно мы постоянно ошибаемся. Мы используем атомарные разделы и атомарные странички, на которые можно сослаться из других разделов.
- Мы общаемся с коллегами, делимся опытом, рассказываем о проделанной работе. И это мотивирует: наводим порядок в своих системах, и коллеги из других систем видят, как удобно и быстро находить информацию. Они начинают структурировать документацию в своих спейсах. Стараемся быть примером, и тогда в нашем хаосе становится чуть больше порядка.
