Привет! Я Олеся, аналитик fuse8. В этой статье я хочу поделиться подходом к организации документации. Он в свое время помог мне быстро войти в новый крупный проект и выстроить все так, чтобы команда не тонула в хаотичных требованиях и легко находила нужное в любой момент.
Предисловие
Моё становление как аналитика было, можно сказать, с места в карьер. Я сразу попала на очень объёмный, сложный проект, богатый на функции и требования, а времени на погружение, как водится, было минимум. И первое, что я должна была сделать, это как раз организовать документацию.
Клиент не требовал делать все по ГОСТу. Но ему критически важно было в итоге получить подробную, исчерпывающую и актуальную документацию, которая была бы понятна любому читателю: и тому, кто давно работает на проекте и ищет ответ на свой вопрос, и тому, кто только присоединяется к команде и знакомится с тем, что уже было сделано.
Вместе мы сформировали такую структуру, где все «разложено по шкафчикам, а в шкафчиках — по полочкам». И дальше все пошло как по рельсам. Этим опытом я и хочу поделиться. В первую очередь для тех, кто, как и я когда-то, оказался в начале карьеры посреди большого проекта и не знает, с какой стороны подступиться ко всем этим документам.
Зачем проекту документация
Документация — это главный артефакт проекта, результат работы аналитика и основополагающая часть разработки.
По сути, это хранилище всех знаний о разрабатываемом продукте, которое помогает команде работать быстрее и эффективнее — без зависимости от конкретных людей и бесконечных повторных обсуждений одного и того же. Документацией пользуются абсолютно все участники процесса: аналитики, ПМ-ы, дизайнеры, архитекторы, разработчики, тестировщики и т.д.
Хорошо структурированная документация — это полноценный источник правды о продукте, который экономит время и тем, кто давно в проекте, и тем, кто к нему только присоединился.
Та структура, которую мы создали на моем первом проекте, имеет множество ответвлений (помните — проект же большой). Но мне бы хотелось остановиться именно на базовых составляющих — спецификациях, которые служили основой на протяжении всей разработки продукта.
Нулевая спецификация
В этом документе мы собираем общие требования к реализации продукта. Он предназначен для команды, которая будет работать над проектом и проверять корректность его реализации. По сути, именно с этого документа и начинается проект.
Но не получится один раз его собрать и забыть. Важно регулярно актуализировать нулевую спецификацию по мере того, как проект развивается. В процессе могут появляться новые интеграции, расширяться стек, уточняться требования к безопасности и/или производительности. Все это важно фиксировать и отражать в доке.
Вот основные блоки нулевой спецификации:
- Стек технологий — фронтенд, бэкенд, инфраструктура.
- Требования к фронтенду и интерфейсам — общие требования к разработке, требования к дизайну (цвета, сетка, отступы и пр.), интеграционные интерфейсы (REST API, Rabbit MQ, бэкенд-фронтенд и т.д.).
- Требования к данным — работа сервера, структура БД, типы и форматы полей, хранение и утилизация данных.
- Требования к SEO — индексирование, метаданные страниц.
- Атрибуты качества — производительность, надёжность, безопасность, масштабируемость, тестируемость и другие характеристики, определяющие качество продукта.
- Метрики и логирование — технические метрики, логирование событий.
При необходимости, этот список можно расширить или наоборот сократить. Все зависит от масштаба и специфики именно вашего проекта.
Основной профит нулевой спецификации в том, что она дает всей команде единое понимание продукта — того, над чем предстоит работать следующие недели или даже месяцы.
Хорошо собранная нулевая спецификация…
- исключает разночтения между всеми участниками процесса;
- помогает при планировании и оценке ресурсов;
- служит основным фундаментом для тестирования;
- обеспечивает прозрачность перед заказчиком;
- становится базой для новых сотрудников: когда в команду приходит новый человек, этот документ даст ему исчерпывающее понимание продукта и инструментов, с которыми предстоит работать.
Спецификация функции
Следующий слой документации — спецификация функции. Такой документ мы составляем на каждый раздел продукта отдельно. А если раздел очень объёмный, можем даже поделить его на несколько спецификаций на основе функциональных блоков.
Каждая спецификация функции состоит из нескольких частей:
- Общая информация — описание самой функции и ссылки на сценарии использования, библиотеку макетов, сценарии тестирования, архитектуру и требования к SEO (при необходимости).
- Карта переходов — на какие страницы пользователь может переходить в рамках данной функции.
- Функциональные требования — самая объёмная часть спецификации, подробнее о ней ниже.
- Требования к данным — логическая модель данных, а именно та её часть, которая необходима для разработки описываемой функции, а также подробное описание содержимого таблиц БД.
Как устроены функциональные требования
Структура этой части позволяет нам описать каждый блок, не упустив важного. При этом информация организована так, чтобы каждый мог быстро найти то, что ему нужно.
В нашем случае 90% спецификаций опирались на макеты интерфейсов разрабатываемых функций. Дизайнер разделял макет на функциональные блоки, и порядок документации был основан на них.
В итоге, каждый блок содержал вот такую информацию:
- Кликабельность — перечень всех кликабельных компонентов блока интерфейса.
- Эффект наведения курсора — перечень и поведение ховеров.
- Эффект анимации — перечень и поведение кейсов, предусматривающих анимацию при взаимодействии пользователя с интерфейсом.
- Логика работы — логика работы всего блока со ссылками на спецификацию API (например, Swagger), макеты (например, Figma), всю информацию о поведении и корнер-кейсах.
- Особенности адаптации — перечень особенностей интерфейса, когда отображение или поведение отличается от десктопной версии.
Важная задача для аналитика — поддерживать спецификацию в актуальном виде. Но хорошая новость в том, что, придерживаясь такой структуры, как я описала выше, делать это гораздо проще.
И еще момент. Раз уж мы пошли не по ГОСТу и оставили себе место для творчества, важно помнить о балансе. Документ должен быть подробным, но не раздутым. Чтобы читатель не тратил время на «воду», я стараюсь излагать все простым, кратким и максимально понятным языком. Это в первую очередь вопрос бережного отношения к своему и чужому времени 🙂
Организация дизайна: библиотека компонентов
Следующий шаг — организация библиотеки компонентов интерфейса. Номер-один инструмент для дизайнеров и фронтендеров. У нас это обычно фрейм в Figma (у вас это может быть какой‑то альтернативный инструмент), где собраны все используемые компоненты, визуализировано их поведение и зафиксированы общие требования к дизайну в рамках проекта.
А если конкретнее, то там есть:
- все переиспользуемые компоненты интерфейса (кнопки, ссылки, табы, пагинация, хлебные крошки и т.д.) и их состояния: default, hover, active, disabled, error;
- все цвета, использующиеся в дизайне;
- иконки и логотипы;
- сетка с учетом отступов для всех возможных адаптаций;
- типографика — шрифты, их размер, цвет, отступы;
- общие требования к модальным окнам и поп-апам и т.д.
Такой артефакт необходим на любом проекте. И его полезность особенно ощутима, когда речь идёт о чём‑то большом и долгосрочном. Проект растёт, приходят новые люди — дизайнеры, фронтендеры. Важно, чтобы всем им было на что опереться. Если единой библиотеки нет, реализация одного и того же компонента может отличаться от человека к человеку. А это визуальная несогласованность и затраты на переделки.
Оптимально начинать формировать библиотеку компонентов, когда уже сложились первые устойчивые UI-паттерны и повторяющиеся элементы — как правило, это завершающий этап формирования дизайн-системы или начало активной разработки фронтенда. Главное не откладывать.
Что в итоге даёт библиотека компонентов:
- консистентный интерфейс — кнопки, формы, таблицы и др. выглядят одинаково во всём продукте;
- разработчики не создают одни и те же компоненты заново на каждом экране, а используют уже готовые;
- один хорошо протестированный компонент надёжнее, чем десятки его копий;
- проще согласовывать новые решения;
- при описании спецификаций не нужно каждый раз описывать поведение компонента, достаточно сослаться на библиотеку.
Вывод
Получается, что три базовых составляющих документации проекта у нас это:
- нулевая спецификация — общие требования к продукту, которые дают всей команде единое понимание того, что строим и как;
- спецификация функции — детальное описание каждого раздела и фичи, на которое опираются разработчики и тестировщики;
- библиотека компонентов — единый источник правды по всем UI-элементам проекта.
Такая организация делает документацию живым инструментом, а не запутанным архивом с кучей всего, непонятно как описанным и по разным местам разбросанным. Когда все четко, понятно и на своих местах, команда не тратит время на поиск ответов и лишние созвоны:
- разработчик не додумывает реализацию по макету, а опирается на документ;
- тестировщик видит все сценарии и корнер-кейсы;
- клиент еще «на берегу» понимает, как будет работать каждая функция, и, если появляется необходимость, успевает скорректировать что‑то еще до начала разработки.
Ну а мне, как аналитику, проще поддерживать актуальность всей базы знаний по проекту и ориентироваться в этом большом объёме информации.
Чтобы не быть голословной, я попросила нашего лида-фронтендера, с которым мы работали на этом проекте, поделиться, а как вообще ему такая структура и организация документации. Вот, что он говорит:
Мне было приятно работать со структурированной документацией. Я придерживаюсь правила, если что‑то можно стандартизировать, то лучше это сделать и зафиксировать. И описанный Олесей подход отлично это отражает. Лично для меня самым полезным оказалось подробное описание функционала в логике работы. А также базовые концепции: нулевая спецификация и единый подход компонентов
Это был мой опыт организации документации на первом проекте. Надеюсь, он будет полезен таким же начинающим аналитикам, каким я была пару лет назад. Пользуйтесь, адаптируйте под себя и свой проект.
И помните: главный секрет в том, что документация — это история, которая постоянно трансформируется по ходу разработки. Её нельзя высечь в камне и навсегда заморозить. Она живёт вместе с проектом, растёт и меняется вместе с ним. И это нормально. А мы, как аналитики, должны быть готовы её поддерживать, актуализировать и не бояться менять 🙂
