Привет, Хабр! Меня зовут Руслан Назаров, я директор по разработке систем хранения данных TATLIN.FLEX в YADRO. Недавно я начал возрождать культуру составления спецификаций, и вот первые результаты, которыми я хочу поделиться. Мы с командой выстроили процесс работы, подобрали оптимальных участников, составили шаблоны и проверили их в работе. В этом материале расскажу, с чего начать, если в вашей компании спеки еще не написаны, и поделюсь шаблоном — его можно скачать по ссылке в конце статьи.
Определимся, о какой спецификации пойдет речь. Спецификация — это документ, в котором описано, что именно должна делать система с точки зрения функций, поведения и взаимодействия с пользователем.
Иногда работа со спецификацией воспринимается как бесконечная бюрократия, особенно для одного-двух сотрудников, которые стали своеобразными архивариусами команды. Но я уверен, что информацией нужно обмениваться, а не замыкать все данные в одной голове. Иначе мы сами себе создаем бутылочное горлышко.
Чтобы этого избежать, я предложил коллективную работу над спецификациями. При таком подходе сохраняются формальная структура документов и пул экспертов, которые разбираются лучше других. Но эти составляющие помогают процессу, а не тормозят его.
Спецификация нужна всем: разработчикам, тестировщикам, техническим писателям и, конечно, сервисным инженерам. К тому же, на основе спек по фичам, компонентам и системам строится публичная пользовательская документация, которую мы используем в продукте.
Кто пишет спецификации
В основе процесса находится feature-лид, который хорошо разбирается в особенностях продукта. Ему в помощь мы определили QA-лида, потому что такой специалист смотрит на код с точки зрения использования.
В процессе отладки появилась еще одна роль — куратор. По дефолту эту роль берет на себя тимлид feature-лидов. Он знает все дедлайны, может распределять роли в команде и фокусировать инженеров на главном. Дело в том, что мы изначально не закладывали в feature- и QA-лидов менеджерские задачи: проведение встреч, отслеживание контрольных точек и поиск ресурсов. Это все мы передали тимлиду.
Еще в контуре есть разработчики. Например, мы разрабатываем что-то в Kernel Space — надо поддержать User Space, прокинуть в User Interface. Есть и тестировщики. Когда делаем новую фичу, то сперва смотрим на ручное тестирование, пишем сценарий, потом формируем набор тест-кейсов для автоматизации. Или берем старую фичу: сперва прогоняем известные автотесты, потом подключаем ручное тестирование, чтобы копнуть глубже.
Всю эту коллаборацию нужно оркестрировать, поэтому потребовалась новая роль — тимлид feature- и QA-лидов в качестве резерва. Он несет ответственность за фичу, ее оценку и менеджмент по ресурсам и людям как внутри команды, так и с другими командами.
Кто принимает спецификации
Продакт-менеджер — приносит бизнес-фичи и транслирует видение бизнеса или сервиса.
Я, директор по разработке, — провожу фичу через все этапы разработки, чтобы определить полноту с точки зрения дизайна, совместимость с другими фичами, учесть все из нашего опыта.
Технический писатель — первый внутренний заказчик спецификаций. Тот, кто работает с ними, и потом превращает в публичную документацию.
Коллеги из сервиса — им мы передаем фичу. Вышел релиз, фича только родилась. Но нам надо дать мануалы, объяснить, как теперь эта птица полетит, и собрать обратную связь. Все это мы вложим в спеку.
Процесс создания спецификации
Выстроить такой процесс можно поэтапно:
Требования
Их разбирает QA-лид или feature-лид, а на встречах с продуктом мы пытаемся понять: полная ли картина сценариев? Все ли мы понимаем из требований, ожиданий и ограничений?
Заходим в этап исследования. Более того, уже на этапе требований мы входим в исследование. Вообще, проходя каждый этап, мы захватываем следующий — и это позволяет нам входить в него не с нуля, а с готовым черновиком.
Исследования
Зашли в исследование — выходит на арену наша новая роль, feature-тимлид. Происходит серия встреч: внутрикомандные ежедневные или еженедельные синки по поиску дополнительных материалов. Все они используются в дизайне и в проектировании.
Проектирование
Здесь разработчики должны договориться об API, сценариях, метаданных, а также объяснить друг другу, как и что будет работать.
Демо 1: первая публичная контрольная точка
Проходит первое демо — публичная встреча за пределами нашего исходного круга. Мы демонстрируем архитектуру и декомпозицию. На этом этапе уже можем:
разделить задачу, разбить эпик по задачам;
понять, какие ресурсы нам нужны: железо, другие инженеры, другие команды.
Разработка
Разработали, дописали спеку, вложили внутренние API, списки ошибок — словом, все то, что позволяет разработчикам погрузиться на этапе отработки багов и переработки фичи.
Демо 2: мастер-класс для тестирования
Мы снижаем вхождение в эту фичу, чтобы тестирование началось раньше. Получаем еще одну порцию обратной связи. Все так же последовательно корректируем спеку.
Тестирование
Протестировали, замерили перфоманс, проверили свои сценарии, провели итоговое, третье, демо для внедрения.
Обслуживание
Снова появляются коллеги из L3, появляется продукт в обязательном порядке. Так-то они могут присутствовать и на всех этапах. Мы фиксируем то, что уходит:
в качестве рекомендаций;
в качестве дополнительных инструментов;
в обслуживании всего того, что уходит за рамки требований и нашего представления о реализации.
Проходя все эти этапы, мы постепенно разрабатываем фичу. У нас есть контрольные точки, мы на них синхронизируемся, проводим корректировки. И в каждый этап входим подготовленным, потому что уже на первых этапах появляются черновики следующих.
Как это развивалось в моей команде
Почему процесс работы над спецификацией такой сложный? Расскажу, как мы настраивали его в TATLIN.FLEX в течение года.
Весной прошлого года мы выбрали исполнителей: кто будет feature-лидом, кто — QA-лидом. Определились с шаблонами: срастили опыт из RAIDIX и шаблоны из других команд разработки СХД.
Летом начался этап отладки. За этот период я провел 26 индивидуальных и 31 кросс-командную встречу. Мы разрабатывали параллельно пять спецификаций и дополняли шаблоны, создавали новые, вносили правки.
Осенью мы перешли в период внедрения. К процессу подключились лиды по управлению. За это время наладили процесс, собрали обратную связь, сделали несколько корректировок. Зима близко.
Зимой главной целью стало наблюдение. Нам нужно было понять, как процесс живет в автономном режиме и как передают знания разработчики, которые уже поучаствовали в нем. Развитие спецификаций вообще держатся на носителях знаний, поэтому советую работать с ними.
Весной мы провели ретроспективу и пополнили чек-лист прямо в наших шаблонах, чтобы написание спеки превратилось в понятный ритуал. Далее мы движемся в автоматизацию Docs-as-Code для часто меняющихся разделов спеки, которая в первую очередь затрагивает исходный код. Это важно для поддержания актуальности материалов, что мы делаем на каждом код-ревью.
Какие материалы у нас появились
Это наше дерево страниц:
Оно большое, потому что у него есть две задачи:
Помогать описывать новые фичи.
Актуализировать старые фичи.
Не пугайтесь масштабов, потому что шаблон — это кусок мрамора. Мы должны от него отсечь лишнее. Мы получим законченный результат, если уберем ненужные структуры и пустые таблицы.
Какие есть разделы
Разделы напрямую связаны с этапами разработки.
Раздел | Что внутри | Зачем |
|---|---|---|
Требования | Бизнес-сценарии, функциональные требования, ограничения, приоритизация | Feature-лид и QA-лид погружаются, собираем материалы |
Исследование | Контекст, компоненты оборудования, ссылки на базу знаний, выступления, шаблоны прогонов | Накопление знаний, инкубатор предметной области |
Проектирование | API, сценарии, коммуникации, системные компоненты | Разработчики договариваются о взаимодействии |
Разработка | Внутренние API, структуры данных, метаданные, списки ошибок | Погружение на этапе багфикса и переработки |
Тестирование | Позитивные/негативные сценарии, связка с автотестами, быстрые старты | Снижение порога входа для тестировщиков |
Сервис | Workarounds, известные проблемы, рекомендации для L3 | Передача знаний сервису, фиксация опыта |
Все начинается с требований. Как я писал выше, feature-лид и QA-лид погружаются и собирают материалы. Начинается исследование, в процессе которого мы собираем контекст. Итоговые данные мы копим и линкуем, чтобы знания не терялись.
Таким образом, у нас появился шаблон, которым вы тоже можете воспользоваться. Скачивайте шаблон по ссылке →
В дальнейшем их станет только больше, потому что процесс устаканится и мы будем все чаще выходить на однотипные этапы с точки зрения задач и форматов.
Что уже написано
Мы уже закончили несколько спецификаций, еще пара сейчас в работе и проходит этапы создания, о которых я писал выше. У каждой спецификации есть своя нумерация и версионирование — удобно для навигации. Версионирование спеки связано с версией продукта, в котором она выпускается:
Ну а для ориентирования есть и вот такая карта слоев. У Данте их было девять, у нас — пять: Storage, Controller, Cluster, Environment и Product:
Я сформулировал для себя несколько принципов, пока работал со спецификациями и наблюдал за развитием процесса:
Спека — это точка входа
Когда-то документация воспринималась как формальность: написал — и забыл. Сейчас я понимаю: заранее подготовленный шаблон с четкими разделами и этапами снимает большую часть хаоса. Спека становится единым источником правды для всей команды.
Коллективная работа > одиночное геройство
Истории про «архивариусов» научили меня: знания не должны застревать в одной голове. Дуализм ролей, кросс-командные встречи, резервирование — это не избыточность, а отказоустойчивость процесса.
Лучше работать итерациями
Мы не ждем идеального процесса, мы его отлаживаем в работе. Обратная связь, корректировки, ретроспективы — часть культуры.
Отсекайте лишнее от шаблонов
Шаблон спецификации большой не потому, что мы любим многословие. Он большой, потому что должен покрывать и новые, и старые фичи. Но вы не обязаны заполнять все. Отсекайте лишнее. Получайте законченный результат.
Единая точка входа > разрозненные документы
Не надо хранить все в одном файле. Ссылайтесь, агрегируйте, линкуйте. Главное — чтобы спека была тем местом, куда приходит человек за пониманием фичи.
Адаптация процесса — не разовая задача, а постоянная работа над культурой команды. Правильно выстроенный процесс делает команду сильнее, повышает качество продукта и создает среду, в которой знания не теряются, а множатся.
Мы расширяем команды TATLIN и ищем новых специалистов. Ниже — актуальные вакансии:
Если есть вопросы или идеи, как сделать спеки еще лучше, пишите в комментариях. Давайте развивать культуру спецификаций вместе.
