Содержание · 10
Большая часть документации дизайн-систем не читается. Разбираем, какие разделы действительно нужны и как оформлять правила, чтобы им следовали.
Документацию читают в двух случаях
Первый — когда что-то не работает как ожидалось. Второй — когда нужно решить, какой компонент использовать. Всё остальное пролистывают.
Отсюда структура: сначала «когда использовать», потом «как выглядит», потом «варианты и состояния», и только затем всё прочее.
Структура страницы компонента
Одинаковая для всех компонентов — это само по себе экономит время.
Делай / не делай
Самый работающий формат документации — пары примеров. Одна картинка с правильным использованием, вторая с типичной ошибкой и коротким объяснением почему.
Такие пары читают даже те, кто не читает текст, — и именно они предотвращают большинство неправильных применений.
Чего не должно быть
Документация теряет доверие от двух вещей: устаревших примеров и общих рассуждений о ценностях дизайна. Первое видно сразу, второе никто не читает.
- Скриншотов вместо живых компонентов — они устаревают молча.
- Философии на три экрана перед описанием кнопки.
- Правил без объяснения причины.
- Разделов «в разработке», висящих полгода.
Как поддерживать
Документация живёт, если её обновление — часть процесса выпуска компонента, а не отдельная задача «когда будет время». Практика простая: компонент не считается выпущенным, пока не описан.
Документацию не читают целиком — в неё заглядывают. Всё, что нельзя найти за полминуты, написано зря.
Почему документацию перестают читать
Документация умирает не от нехватки текста, а от расхождения с кодом. Как только описание компонента отстаёт от реального поведения хотя бы в одном месте, доверие к ней падает целиком: разработчик один раз обжигается и дальше идёт в исходники. Поэтому первый вопрос к системе документации не «как оформить», а «как гарантировать, что она не разойдётся».
Работающих ответов два: генерировать справочник свойств прямо из типов и хранить примеры как живые экземпляры компонента, а не как скриншоты. Всё, что написано руками и не проверяется сборкой, устаревает — вопрос только в сроке.
Что обязано быть в описании компонента
- Назначение в одну фразу и — отдельно — когда его брать не надо.
- Состояния целиком: пустое, загрузка, ошибка, отказ в доступе, предельно длинный текст.
- Правила содержимого: длина подписи, допустимость переноса, что делать с числами.
- Доступность: роль, обход клавиатурой, что объявляется вспомогательной технологией.
- История изменений с датами — иначе непонятно, что успело устареть.
Как делят систему на части
Самая известная схема деления — атомарный дизайн: атомы, молекулы, организмы, шаблоны, страницы. Кнопка — атом, поле с подписью и кнопкой — молекула, шапка сайта — организм. Схема полезна не названиями, а вопросом, который она заставляет задать: из чего состоит этот элемент и можно ли его собрать из уже существующих.
На практике пятиуровневое деление почти всегда сокращают до трёх: примитивы, компоненты и блоки страницы. Причина простая — граница между молекулой и организмом спорна, и команда тратит время на классификацию вместо работы. Полезнее договориться, что примитив не знает о данных, компонент знает о своих, а блок — о странице.
Что описывают у каждого уровня
- Примитив: токены, размеры, состояния. Никаких упоминаний, где он применяется.
- Компонент: назначение, варианты, границы применения и хотя бы один пример «не так».
- Блок: из чего собран и какие данные ему нужны; отдельного визуального описания у него нет.
- Версия: у системы она одна, и в примечаниях к выпуску пишут не «улучшили», а что сломается при обновлении.
- Устаревшие компоненты не удаляют молча: помечают, называют замену и дату, после которой поддержки нет.
Что в итоге
Документацию читают ради двух вопросов: какой компонент взять и почему он ведёт себя не так. Отвечайте на них первыми.
Пары «делай / не делай», живые примеры и дата обновления делают документацию полезной больше, чем любой объём текста.
Коротко
- Почему документацию перестают читать?
- Из-за расхождения с кодом: достаточно одного неверного описания, чтобы доверие пропало ко всей документации. Поэтому справочник свойств генерируют из типов, а примеры хранят как живые компоненты.
- Что обязательно должно быть в описании компонента?
- Назначение, когда его брать не надо, полный набор состояний, правила содержимого и доступность. Раздел «когда не надо» экономит больше всего времени.
Иконки в интерфейсе
Как строить иконки на единой сетке, какую толщину линии выбрать, когда нужны подписи и почему универсальных иконок почти не бывает.ДальшеЧитайте также
Посмотреть примеры
Нашли ошибку или неточность в атрибуции? Напишите нам
Обсуждение
Загружаем…