Как писать гайды

Контур.Гайды написаны в одном стиле: они объясняют, как делать правильно, а не перечисляют запреты. Так читателю проще найти нужное правило и доверять источнику. Если вы пишете новый гайд, прочитайте эти советы до начала работы.

Прежде чем писать, решите, нужен ли отдельный гайд. Если практика, которую вы хотите зафиксировать, умещается в одну-две фразы и её можно отнести к существующему гайду, дополните его.

Гайды бывают двух видов: одни рассказывают про принципы, другие — про контролы.

Гайд про принцип описывает не контрол, инструмент или библиотеку, а общее правило проектирования интерфейса: как построить лейаут, выбрать отступ и цвет, отреагировать на действие пользователя. Такое правило работает одинаково в любом продукте.

У гайда про принцип нет жёсткой структуры. Начните с короткого определения: что это за принцип и зачем он нужен. Затем раскройте мысль и приведите примеры.

Начните гайд про контрол с определения: что это за контрол и зачем он нужен.

Разбейте описание контрола на разделы:

• Когда использовать — в каких сценариях контрол подходит, а в каких нет.
• Описание работы — настройки, режимы и поведение контрола.
• Название — какой текст писать в контроле и его элементах.
• Дизайн — внешний вид, отступы и место контрола на странице.
• Валидация — когда и как показывать ошибки.
• Доступность — управление с клавиатуры, фокус, семантическая вёрстка.
• Адаптивность — как контрол ведёт себя на экранах разной ширины.
• Анимация — как контрол реагирует на наведение, нажатие и другие действия.

Гайд может содержать не все эти разделы, либо содержать уникальные.

Делайте каждый раздел самостоятельным, с минимумом отсылок к другим частям текста: читатель часто приходит по ссылке сразу в нужное место.

Одинаковое поведение разных контролов описывайте одной и той же формулировкой во всех гайдах — так читатель узнаёт знакомое правило.

Пишите в информационном стиле: простой синтаксис, живые глаголы вместо модальных, активный залог вместо пассивного. Остальные правила — в редполитике.

Не используйте канцелярит и усилители вроде «очень» и «максимально»: они удлиняют фразу, но не добавляют смысла.

Убирайте пустые связки: «также», «при этом», «таким образом», «тем самым». Без них смысл обычно не меняется.

Не пишите «позволяет» — перестройте фразу через «можно» или активный глагол.

Не пишите рекомендации через «должен», «нужно», «необходимо».

Меняйте канцелярит на короткий оборот.

Не пишите общих фраз, которые подчёркивают важность или призывают делать хорошо, но ничего не сообщают: «улучшает пользовательский опыт», «делает интерфейс удобнее».

Неправильно

Обходитесь без «мы»: оно уводит текст в самопрезентацию, а гайд даёт прямую инструкцию. Обычно фразу можно перестроить в повелительное наклонение.

Обращайтесь к читателю на «вы» со строчной буквы.

Не ущемляйте букву «ё» — используйте её в словах, где она должна быть.

Оформляйте перечисления списком. Пункты одного списка начинайте одинаково: либо все с глагола, либо все с существительного.

Не повторяйте заголовки внутри гайда — иначе по ним сложно ориентироваться и на них нельзя поставить точную ссылку.

Одна мысль — один абзац. Если в абзаце появилось второе правило, разделите его на два.

Пишите рекомендации в повелительном наклонении — как прямую инструкцию:

• «Используйте радиокнопки, только если вариантов не больше пяти».
• «Показывайте меню на странице постоянно, а не только по наведению».
• «Старайтесь не называть кнопку в две строки: делайте кнопку шире или меняйте название».

Начинайте абзац с правила, а потом объясняйте причину.

Правильно

Если упоминаете другой контрол или гайд, делайте упоминание ссылкой: перейти по ней быстрее, чем искать гайд в меню.

Не используйте внутренние термины Контура: внешнему читателю они непонятны. Если без термина не обойтись, поясните его на полях.

Проверьте готовый текст на орфографию и пунктуацию: прогоните через Главреда и нейросеть со скиллом /kontur-ui-guides-editor.

Называйте контрол так же, как называется гайд про него. Жаргон и англицизмы в гайдах — норма: «тогл», «хинт», «тост», «сайдпейдж», «пейджинг», «комбобокс», «скролл». Гайды читают дизайнеры и разработчики, поэтому не заменяйте профессиональные слова бытовыми.

Пишите «раскрывающийся список», а не «выпадающий список» или «выпадашка»: список раскрывается, а не выпадает.

Пишите «скролл», «скроллить» и «скролл-бар», а не «прокрутка», «прокручивать» и «полоса прокрутки».

В основном тексте пишите «модальное окно». «Модалку» оставьте для сноски на полях, где объясняете жаргон.

Используйте кавычки-ёлочки «», а внутри ёлочек — „лапки“.

Не путайте тире и дефис.

Дефис (-) ставится только внутри слов: «какой-то», «из-за».

Тире (—) ставится между словами с обычными пробелами. В диапазоне чисел тире пишется без пробелов: 300—450 px, а если в границах диапазона есть слова — с пробелами: 17 фев — 17 мар.

Единицы измерения и знаки %, № отбивайте от числа неразрывным пробелом: 24 px, 90 %, № 5.

Остальные правила набора смотрите в гайде «Экранная типографика».

Код выделяйте стилем с заливкой фона и моноширинным шрифтом:

Клавиши и сочетания клавиш оформляйте стилем с обводкой и тенью: Enter или ⌥ →.

Выбирайте формулировку по жёсткости правила:

• «Лучше» — есть предпочтительный вариант, но другой не ошибка.
• «Допустимо» — ограниченное исключение из правила.
• «Не используйте» — обычный запрет, всегда с причиной.
• «Нельзя» — жёсткое правило без исключений.

Объясняйте, почему правило именно такое, и подкрепляйте его фактами, примерами и историей интерфейсов: такие инструкции интереснее читать и проще применить.

Берите примеры из интерфейсов Контура. Даже для примера «как не надо» возьмите скриншот сервиса Контура или нарисуйте картинку специально. Примеры из чужих интерфейсов выносите на поля.

Делайте примеры наглядными:

• иллюстрируйте одно правило;
• используйте пару «Неправильно» / «Правильно»;
• показывайте реальный пример, а не абстрактный;
• уберите лишние детали, оставьте только главное.

Подписывайте иллюстрацию, если без подписи непонятно, что на ней. Подпись ставьте под картинкой: одна короткая мысль без точки в конце.

Добавляйте к картинке alt-текст — короткое описание того, что на ней. Он нужен читателям со скринридером, нейросетям и тем, у кого картинка не загрузилась.

Делайте иллюстрации не шире 700 px — это ширина колонки гайда.

Автоматический переход из одного состояния в другое показывайте стрелкой.

Если состояние меняется по нажатию клавиши, покажите на картинке, какую клавишу нажали.

Если движение или переход не передать стрелками, добавьте короткую анимацию: GIF или зацикленное видео .mp4 без звука.

Показывайте в одном ролике один сценарий и не делайте его длиннее нескольких секунд.

Чтобы показать, как делать нельзя, приведите пару «Неправильно — Правильно»: сначала неправильные варианты, затем правильный.

Неправильно

Правильно

Если вариант не ошибка, но и не лучший, отметьте его жёлтой меткой «Допустимо».

Если правильный пример придумать сложно, неправильный вариант можно просто перечеркнуть. Проверьте, что линия не закрывает важные детали интерфейса.

Сохраняйте каждую картинку в двух размерах — 100 % и 200 %. Называйте картинки по имени контрола с порядковым номером: Modal_001.png и Modal_001@2x.png, где:

• Modal — название контрола на английском;
• 001 — порядковый номер картинки в гайде;
• 2x — суффикс картинки для ретиновых экранов.

Перед публикацией проверьте гайд по списку:

• орфография и пунктуация проверены, текст прогнан через нейросеть с использованием скилла;
• нет канцелярита, «должен», «нужно», «позволяет», «мы» и пустых связок;
• у каждого запрета и рекомендации есть причина;
• в абзаце одна мысль, и он начинается с правила;
• «ё» стоит везде, где она есть;
• контролы названы так же, как гайды про них;
• нет «выпадающего списка», «прокрутки» и «модалки» в основном тексте;
• нет внутренних терминов Контура без пояснения;
• упоминания контролов и гайдов оформлены ссылками;
• заголовки не повторяются, пункты списков однородные;
• кавычки — ёлочки, тире и дефис на своих местах, числа и единицы отбиты неразрывным пробелом (50 px, 90 %);
• примеры взяты из интерфейсов Контура, нет картинок-заглушек;
• картинки сохранены в 100 % и 200 %, названы по схеме Modal_001.png, не шире 700 px, с alt-текстом.