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

Контур.Гайды выдержаны в одном стиле: в них рассказано, как делать правильно, и нет тональности запретительных законов. Советы, собранные здесь, помогут вам придерживаться этого стиля. Прочитайте их перед началом работы над новым гайдом.

Используйте информационный стиль текста: простой синтаксис, нормальные глаголы вместо модальных, подлежащее вместо пассивного залога и другие правила из редполитики.

Избегайте канцеляризмов и усилителей оценки. Подкрепляйте рекомендации фактами или иллюстрациями.

Избегайте общих или очевидных формулировок, которые показывают важность или призывают делать хорошо, но не сообщают никакой полезной информации.

Не используйте местоимение «мы» там, где можно без него обойтись, даже если это породит пассивный залог.

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

Ссылаясь на другой гайд, дайте выжимку этого гайда. Например, в случаях с валидацией или анимацией.

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

Есть несколько способов что-то запретить:

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

Поясняйте, почему что-то запрещается или рекомендуется делать определенным образом. Гайд становится интереснее и полезнее, если помимо сухих инструкций содержит примеры, пояснения и выдержки из истории интерфейсов.

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

• Когда использовать — контекст применения.
• Примеры (варианты) использования — рекомендации по использованию, примеры применения компонента, допустимые варианты, которые можно собрать из компонента библиотеки.
• Описание работы. То же, что и спецификация — настройки и режимы работы и детальное описание, как компонент ведет себя.

Рекомендации по использованию компонента пишите в форме призыва:

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

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

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

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

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

• Краткое описание без заголовка
• Когда использовать
• Примеры использования
  • Название (текст лэйблов, заголовки)
  • Состояние по умолчанию
• Описание работы
  • Размер и расположение
  • Фокус и работа с клавиатурой
  • Валидация
  • Дизайн и анимация

Для обозначения пикселей используйте сокращение px, отбивайте его тонким пробелом: 50 px.

Знаки № и % также отбивайте тонким пробелом, в html —  .

Не путайте длинные тире и дефисы. В диапазонах используйте среднее тире.

Используйте математические символы, там где они необходимы. Например знак минуса − вместо дефиса -, знак умножения × вместо буквы x.

В словах с неочевидным ударением показывайте ударную гласную явно: бо́льшая.

При упоминании цвета вставляйте закрашенный кружок размером 14×14 px и код цвета в hex-формате: #E3071C.

Чтобы выделить кусок кода, используйте стиль c заливкой фона и моноширинным шрифтом: -webkit-font-smoothing: antialiased;.

Для обозначения клавиш или клавиатурных сокращений используйте специальный стиль c обводкой и тенью: Enter или ⌥ →.

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

Избегайте слишком больших иллюстраций, оптимальный размер — до 700 px по ширине.

Чтобы показать автоматический переход из одного состояния в другое, используйте стрелки ↓ → из шрифта Lab Grotesque K, цвета #ADADAD:

Если состояние меняется после нажатия клавиши, это иллюстрируется соответствующим образом:

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

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

Если правильный пример придумать сложно и хочется просто показать недопустимость какого-то варианта, можно использовать черту цвета #E3071C под углом 45°. Убедитесь, что линия не перекрывает значимые детали интерфейса.

Все картинки в гайде должны быть сохранены в двух размерах: 100 % и 200 %. Называться должны соответственно: button-green.png и button-green@2x.png, где:

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