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

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

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

Используйте букву «ё».

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

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

Неправильно

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

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

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

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

Избегайте терминов из Контура. Читателю не из Контура может быть непонятно. Если термина избежать не удаётся — сделайте сноску с пояснением.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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