Стайлгайд

Общие принципы

Справка Название компании — это информационное пространство, объединяющее всех участников проекта и обеспечивающее наше комфортное взаимодействие друг с другом. Документация не формальность, а реально работающий инструмент общения между командами проекта. Для того, чтобы этим инструментом пользовались, тексты Справки должны соответствовать следующим критериям:

Уникальность. Перед разработкой нового документа проверьте, есть ли в справке страницы с похожим содержанием. Если аналогичный документ уже добавлен в Справку, возможно, стоит актуализировать его, а не создавать новый.

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

Понятность. Определите, кому адресован ваш документ и посмотрите на текст глазами читателя. Всё ли будет ему понятно? Может, нужно подробнее описать неочевидные моменты, добавить ссылки на внешние или внутренние источники, визуализировать информацию с помощью скриншотов или иллюстраций?

Актуальность. Документация живого и активно развивающегося проекта не может оставаться неизменной. Своевременное обновление информации делает справку Справкой.

Заголовки

Заголовки должны выражать тему следующего за ними раздела.

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

От размера заголовка зависит уровень вложенности раздела. Для крупных разделов используются заголовки H2, для подразделов — заголовки H3. Именно на основе заголовков формируется макрос Оглавление.

Заголовки H4 и H5 лучше не использовать — они плохо выделяются на фоне обычного текста.

Элементы интерфейса

Элементы интерфейса (названия блоков, разделов, вкладок админки, кнопок, страниц и разделов сайта) выделяются полужирным начертанием, без кавычек.

Каждый элемент интерфейса имеет однозначную характеристику.

Текстовое поле (окно для ввода) предназначено для свободного ввода текста.

[здесь должен быть скриншот]

Список представляет собой прокручиваемый список значений, позволяющий выбрать одно или несколько из них.

[здесь должен быть скриншот]

Выпадающий список представляет собой прокручиваемый список значений, который раскрывается при нажатии на специальный значок (треугольник или стрелка).

[здесь должен быть скриншот]

Чекбокс (флажок, галочка) позволяет включить или отключить определенную опцию или функцию. Чекбокс можно включить и отключить.

[здесь должен быть скриншот]

Вкладка (таб) позволяет переключаться между разными страницами или пространствами с набором элементов. Вкладку можно переключить, можно перейти на вкладку.

[здесь должен быть скриншот]

Полоса прокрутки (скролл) позволяет просматривать информацию, не помещающуюся в пределы окна.

[здесь должен быть скриншот]

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

[здесь должен быть скриншот]

Кнопка нужна для выполнения определенной функции по клику (переход по ссылке, раскрытие окна etc.) Кнопку можно нажать.

[здесь должен быть скриншот]

Неразрывные пробелы

Неразрывные пробелы — это специальные символы, которые выглядят как пробел, но при этом (в отличие от обычного пробела) не дают переносить строку, связывая слова в единую конструкцию.

Чтобы поставить неразрывный пробел, нужно выделить пробел и нажать сочетание клавиш alt 255 или alt 0160.

Неразрывные пробелы ставятся:

• между предлогом и последующим словом;
• между глаголом и частицей НЕ;
• между числом и знаком %;
• между инициалами и фамилией;
• во всех иных случаях, когда нежелателен разрыв конструкции.

Дефис и тире

Дефис используется как соединительная черта между словами или частями слова: Город-герой, кое-как, почему-то, etc. Дефис представляет собой короткую горизонтальную черту, при использовании не выделяется пробелами.

Тире предназначено для разделения частей предложений: Дефис — это совсем не то же самое, что тире. Тире представляет собой длинную горизонтальную черту, при использовании выделяется пробелами.

Со стандартной компьютерной клавиатуры по умолчанию можно набрать только дефис — короткую черту. Чтобы набрать тире, нужно нажать сочетание клавиш alt 0151.

Кавычки

Кавычки используются для прямой речи, названий компаний, цитат, выделения слов, используемых в переносном значении etc.

Элементы интерфейса употребляются без кавычек и выделяются полужирным шрифтом.

В качестве кавычек используются кавычки-елочки «». Чтобы поставить кавычки-елочки, необходимо нажать сочетания клавиш alt 0171 для открывающего знака и alt 0187 для закрывающего.

Примечание

Чтобы не запоминать сочетания клавиш для ввода нетривиальных символов, установите типографскую раскладку Ильи Бирмана. Используя эту раскладку, вы сможете прямо с клавиатуры вводить неразрывные пробелы, длинное тире, кавычки-елочки и другие знаки.

Списки

Каждый пункт списка начинается с прописной буквы.

Нумерованный список используется при описании последовательности действий. В конце строк ставится точка или пустой знак.

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

Таблицы

Таблицы используются для структурирования и упорядочивания информации. Они упрощают восприятие текста.

Совет

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

В виде таблицы можно оформить длинный список подобных объектов (например, описание блоков блочного редактора, поля админки инфоблока, etc.)

Шапка таблицы заполняется без знаков препинания в конце строк (за исключением вопросительных и восклицательных знаков).

Тело таблицы заполняется в соответствии с потребностями автора. Знаки препинания в конце строк ячеек не ставятся (за исключением вопросительных и восклицательных знаков).

Информационные панели

Информационные панели бывают нескольких типов:

Информация

Для выделения важной информации, на которой читателю нужно сконцентрировать внимание.

Примечание

Для размещения дополнительной информации. Также в этой панели размещаются ссылки на связанные страницы, задачи в Jira, etc.

Предупреждение

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

Ошибка

Для выделения информации о запрете на совершение определенных действий.

Готово

Для выделения информации по усмотрению автора

Информационные панели можно использовать по своему усмотрению, если текст панели не противоречит значению ее цвета и значка.

Разворачивание

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

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

Ссылки

Ссылки оформляются через макрос Ссылка ctrl + k.

Все ссылки на админку сайта должны вести на прод (если нет конкретной необходимости сослаться на демо, тест или стейдж).

Подчеркивание

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

Курсив

Курсив используется для дополнительного выделения текста по усмотрению автора.

Оглавление

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

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

/Оглавление

Если оглавление слишком большое, лучше убрать его под кат (использовать макрос разворачивание).