Дока — это добрый справочник для веб-разработчиков. Почему добрый? Потому что мы заботимся о том, чтобы наши материалы были актуальны, точны, понятны и полезны. Наше кредо — расскажи просто, покажи красиво.
Чтобы помочь авторам писать тексты для Доки, мы создали это руководство по стилю.
Справочник состоит из шести разделов:
- HTML;
- CSS;
- JavaScript;
- Рецепты;
- Доступность;
- Веб-платформа.
Материалы Доки пишутся в двух жанрах: «дока» и «статья».
Дока — это справочный материал, кратко и формально описывающий некое понятие, например, свойство или тег. Как спецификация, только по-русски и понятным языком.
Статья — это расширенный материал, посвящённый определённому вопросу, с авторским мнением, примерами и рассуждениями. Например, «Руководство по флексбоксам» не только познакомит читателя со спецификацией флексбокса, но и расскажет о раскладке в целом, научит делать её при помощи флексбоксов и покажет примеры из жизни.
При необходимости материалы снабжаются иллюстрациями и демками (интерактивными демо).
В конце наших материалов есть раздел «На практике». Здесь авторы и контрибьюторы могут поделиться своим личным опытом по теме. Ведь теория — это хорошо, но что такое теория без практики? Авторские советы, мнения и трюки могут быть очень полезны!
Мы видим стиль Доки так: уважительный, заботливый, неформальный, слегка шутливый и ироничный. Наша главная цель — понятность и доступность: расскажи просто, покажи красиво.
Постарайтесь донести свою мысль коротко и максимально понятно любому читателю, даже самому начинающему.
Термины и профессиональный жаргон — это хорошо, но при первом употреблении поясните, что значит слово. Используйте современные термины на русском языке — те, которые вы употребили бы в разговоре с коллегой: не «настольный ПК», а «десктоп». Как принято переводить термины, можно посмотреть в словаре терминов по фронтенду. Избегайте транслита.
Не увлекайтесь, но и не пренебрегайте цитированием и ссылками. Если уже есть статья с более подробным описанием того, о чём вы пишете, дайте на неё ссылку. Когда даёте ссылку, пишите в ней не «здесь» и «тут», а название или суть материала, на который ссылаетесь.
Если в вашем тексте появился очень длинный список с вложенностью и кучей текста, подумайте, как разделить его на секции с заголовками и параграфами.
Общайтесь с читателем на равных, он такой же человек и разработчик, как и вы. Обращайтесь к нему уважительно: гендерно-нейтрально и на «вы» («вы» всегда с маленькой). Стоит избегать грубостей, просторечий и неуместных сравнений.
Ирония и незлобный сарказм хороши, но они не должны задевать чувства читателей. Избегайте шуток на неоднозначные темы.
Дока — не учебник и не научный справочник. Избавляйтесь от канцелярита, сложных синтаксических конструкций и наукообразности.
Текст утяжеляют:
- замена глаголов причастиями, деепричастиями и существительными, использование глаголов в пассивной форме, расщепление сказуемого («производимая проверка», «проверка была произведена», «производить проверку» вместо «проверять»);
- нанизывание падежей («необходимость произведения проверки»);
- вводные слова и конструкции («вследствие», «таким образом», «исходя из этого» и т. п.);
- притяжательные местоимения («у этой переменной», «в нашей проектной работе»).
- канцеляризмы («является», «данный», «будучи», «в настоящее время», «вышеизложенный», «осуществлять» и т. п.)
Постарайтесь, чтобы весь текст был написан в одном тоне.
Материалы Доки пишутся в разметке Markdown с небольшими вкраплениями HTML-кода при необходимости. У нас есть некоторые соглашения по оформлению.
Если здесь вы не нашли ответа на вопрос, как оформляется тот или иной элемент текста, посмотрите на портале «Грамота». Если нет и там — оформите, как считаете нужным, редактор разберётся.
Пишем статьи в разметке Markdown. Не используйте HTML там, где можно обойтись маркдауном. Особенности этого языка разметки вы можете найти в официальной документации.
Если вам нужен HTML, то между маркдауном и HTML-кодом должна быть пустая строка, чтобы движок правильно обработал страницу.
Используйте заголовки от <h2> до <h4>:
## Заголовок раздела
### Заголовок подраздела
#### Самый маленький заголовок
**Жирный текст, если четвёртого уровня не хватило**Не используйте заголовок первого уровня. На странице он всегда один и указывается в начале статьи в поле title:
---
title: "Я — название статьи"
---Для заголовков в подбор (в строку) используйте жирный текст:
**Архитектура приложения** — это набор решений о том, как модули приложения будут общаться друг с другом и с внешним миром.Жирным, как правило, выделяются сильные смысловые ударения. Например, указание на важность:
✅ Подсказка-плейсхолдер не должна выступать как замена тегу <label>.
Курсивом выделяются менее важные смысловые ударения. Например, термин или название файла:
✅ SOAP (Simple Object Access Protocol) — формат обмена данными.
✅ В файле .yaspeller.json есть блок dictionary.
Для выделения жирным используйте две звёздочки: **болд**, а для курсива — одно нижнее подчёркивание: _курсив_.
Картинки вставляются так:
Для картинок обязательно указывайте альтернативные описания — то есть что на них изображено.
Как понять, что хорошо описали картинку? Прочтите описание, не глядя на изображение. Если смогли понять, что изображено, то это хорошее описание.
Обратите внимание, что описание:
- не начинается со слов «картинка», «иллюстрация»;
- не содержит дополнительные факты, ссылки, эмодзи и всё, что не относится к картинке;
- не повторяет то, что уже есть в тексте, а ещё подпись к картинке;
- написано по всем правилам русского языка, как любой другой текст.
⛔ 
✅ 
Можете ставить точку в конце описания, тогда скринридеры сделают небольшую паузу во время чтения содержимого. А можете не делать этого, особенно если это одно предложение.
Чтобы добавить картинку с подписью, поместите текст сразу под картинкой, без пустой строки:
Подпись к картинкеПлатформа обернёт картинку в <figure> с текстом в виде <figcaption>.
Если нужно добавить в текст анимацию, отдайте предпочтение видео в формате MP4, а не GIF-изображению: видео легче и его можно поставить на паузу. Уже имеющийся GIF можно конвертировать в MP4 онлайн.
Если вы хотите привлечь внимание к небольшому блоку текста, это можно сделать при помощи специальной разметки для врезок:
<aside>
🥨 Брецель важно есть свежим!
</aside>Между HTML-тегами и содержимым важно оставить пустые строки, чтобы маркдаун отрисовался.
Чтобы у врезки появилась иконка, добавьте в начало подходящий по смыслу эмодзи и отделите его пробелом.
Если вы хотите дать какую-то дополнительную информацию к сведению, скройте её под блоком с подробностями при помощи тегов <details> и <summary>:
<details>
<summary>Подробнее про блок с подробностями</summary>
Здесь может быть длинный текст для тех, кто заинтересовался и раскрыл блок.
</details>Код в тексте — названия тегов, свойств, консольных команд, блоки кода и т. п. выделяйте при помощи обратных апострофов (бэктиков):
✅ Если не задать никакое значение font-size, то браузер использует размер по умолчанию. Обычно это 16 px.
Цифровые значения обычно не выделяются — цифры и так достаточно заметны в поле текста. Единицы измерения отделяются от числа пробелом, их можно записывать как в сокращённом виде (16 px), так и в развёрнутом (16 пикселей).
Однако в случае, когда текст очевидно говорит «свойство — значение», можно выделить значение бэктиками и записать его именно так, как будет в коде:
✅ Задаём свойству margin значение 2px.
Если в заголовках есть код, тоже заключаем его в бэктики:
---
title: "Тег `<table>`"
---Блоки кода выделяются при помощи трёх бэктиков с указанием псевдонима нужного языка:
```css
.container {
display: flex;
}
```Доступные для использования языки и их псевдонимы можно найти в документации Highlight.js.
Для выделений названий файлов, папок, систем и т. п., что не код, но хочется акцентировать — используем курсив:
✅ Наиболее известным JSON-файлом является конфигурационный файл менеджера пакетов npm — package.json.
Шорткаты оборачиваем в тег <kbd>, названия кнопок пишем через пробел, а не через плюс:
⛔ Ctrl + T
✅ Ctrl T
Юникод добавляйте живыми символами, а не мнемоникой:
⛔ →
✅ →
Теги пишем всегда в угловых скобках, чтобы не путать их с другими служебными словами:
⛔ cite
✅ <cite>
В конце названия метода или функции всегда ставим круглые скобки, чтобы подчеркнуть их отличие от свойств:
⛔ Метод forEach принимает колбэк
✅ Метод forEach() принимает колбэк
Вы можете использовать эмодзи в тексте, однако не переборщите.
Удобно искать и копировать эмодзи поможет сайт с набором эмодзи.
Если эмодзи находится в конце строки, знаки препинания после него не ставятся (то есть точка не нужна).
Комментируйте вставки кода — они должны быть понятны. Постарайтесь дать хорошее описание примера перед вставкой кода вместо большого количества комментариев в самом примере:
⛔ Плохо:
При отсутствии точки с запятой можно случайно вернуть неверный результат из функции:
function getValue () {
return
42
}
// Функция возвращает `undefined`, а не `42`,
// потому что JavaScript считает перенос за конец строки✅ Хорошо:
При отсутствии точки с запятой можно случайно вернуть неверный результат из функции. Вот пример функции, которая возвращает undefined, а не 42, потому что JavaScript считает перенос за конец строки:
function getValue () {
return
42
}Комментарии в коде пишем на русском языке над комментируемой строкой. Предложения в комментарии начинаются с заглавной буквы, точка в конце не ставится (иногда по смыслу можно поставить двоеточие). Не злоупотребляйте «закрывающими» комментариями — пользуйтесь ими только в случаях сложной структуры.
li::before {
/* Не забываем о свойстве content */
content: "";
width: 15px;
height: 15px;
border-radius: 50%;
background-color: #ed6742;
/* Задаём позиционирование: */
position: absolute;
left: -25px;
top: 5px;
}Если комментарий используется для отображения вывода или показывает изменённое значение, допустимо ставить его после строки:
const empty = []
console.log(empty.length)
// 0Избегайте ненастоящего кода: оформление комментариев не по правилам того языка, на котором ваш пример, многоточия посреди кода и т. п. Если вам нужно сократить код, напишите, что там должно было быть. Допустим, вы показываете тег <title> и хотите опустить прочие теги в <head>:
<head>
<!-- Здесь что-то про кодировку, заголовок, фавиконку -->
<title>Заголовок</title>
</head>Если вы приводите пример неправильного кода, объясните почему и чётко обозначьте, что так делать нельзя:
⛔ Так делать нельзя: модификатор не следует использовать без блока.
<!-- Не используйте этот код! -->
<p>
Обычный текст, <span class="text--red">красный текст</span>
</p>В конце предложения всегда ставится точка. Вместо точки можно закончить эмодзи 😀
👆 В заголовках точки не ставятся!
В тексте на русском языке используем «ёлочки», а внутри них — „лапки“:
✅ Поиск выдаёт: «Вы искали слово „картошка“».
Англоязычные названия (брендов, компаний, инструментов, статей) в кавычки не берутся:
✅ Компания Apple выпустила новый браузер.
Ссылки делаются внутри кавычек, сами кавычки в ссылку не входят:
✅ Читайте подробнее в статье «[Асинхронность в JS](/js/async-in-js/)».
В сокращениях ставится пробел:
⛔ т.к.
✅ т. к.
Оформляйте списки при помощи цифры с точкой или наборного знака (в маркдауне это дефис). Если у вас список из коротких односоставных однотипных пунктов, можно разделять их точкой с запятой. В этом случае первый пункт пишется с прописной (большой) буквы, последующие со строчной, в конце последнего пункта ставится точка.
1. Один;
1. два;
1. три.
- Один;
- два;
— три.Если перед таким списком у вас идёт обобщающее предложение с двоеточием, первый пункт тоже можно начинать со строчной буквы.
Селекторы бывают:
- тегами;
- классами;
- идентификаторами.
Если у вас список из длинных пунктов (особенно если в пункте не одно предложение), каждый пункт пишется с прописной (большой) буквы, а в конце пункта ставится точка:
1. Проценты. Размер в процентах будет рассчитываться от размеров элемента.
1. Ключевое слово `auto`. Размер изображения остаётся неизменным. Кстати, это ключевое слово является значением по умолчанию.👆 Обратите внимание, что мы используем «ленивые» нумерованные списки, начиная каждый пункт с единицы. Маркдаун сам проставит нужную нумерацию.
Списки в подбор (как в этом предложении) оформляются а) при помощи буквы русского алфавита со скобкой; б) начинаются со строчной (маленькой) буквы; в) разделяются точкой с запятой.
Используйте букву Ё. Мы её любим ❤️
При написании вариантов через косую черту (/) пробелы не ставятся:
⛔ да / нет
✅ да/нет
Однако следует избегать такого написания вариантов, кроме устойчивых случаев. Лучше писать словами:
⛔ ввод/вывод
✅ ввод или вывод
- Оси координат: «ось x» (строчная латинская буква, набранная курсивом).
- Точка: «точка A» (прописная латинская буква).
- Знаки математических действий и соотношений (+ , – , х , : , / , =) отбивают пробелом от смежных символов и чисел.
Если нужно показать ударение в слове, используем обычный кириллический символ с комбинирующим символом ударения (combining acute accent). Его нужно ставить после буквы. Можно зайти на страницу символа, нажать на кнопку «Copy to Clipboard» и вставить его куда нужно. На macOS символ ударения можно найти в панели Character Viewer (Ctrl Cmd Space).
✅ Если можно не мо́кать — лучше не мокать.
У Доки есть не только технические редакторы, но и литературный. Он не участвует в процессе публикации текста — мы хотим быть более «народным» проектом и публиковать статьи максимально быстро. Однако рано или поздно он дойдёт до вашей опубликованной статьи и немного её отполирует. Делать он будет вот что:
-
Проверять логику изложения, указывать на логические несоответствия.
-
Оценивать понятность, помогать развернуть неясные мысли, удостоверяться, что изложенного контента достаточно для понимания темы.
-
Оценивать структуру изложения, искать самый удачный вариант текстовой структуры (разбиения на части, согласованность частей), при которой 1) текст просто и удобно читать; 2) по тексту легко искать информацию.
-
Проводить литературное редактирование: нормализовывать стиль, убирать лишние слова, предложения и мысли, не относящиеся к повествованию; убирать из текста «воду», конкретизировать мысли; убирать из текста речевые и стилистические ошибки; проверять логическую связь предложений внутри абзацев и связь абзацев друг с другом; удостоверяться, что в контенте нет потока мысли и перескакивания с одной мысли на другую; проверять, что синтаксические формы соответствуют смыслу повествования.
-
Оценивать выбранную форму повествования: предлагать альтернативные формы (списки вместо абзацев текста, схемы вместо скриншотов, иллюстрации вместо текста и т. п.)
-
Оценивать занимательность текста: насколько удачно выбраны описательные и повествовательные средства, насколько сохраняется мотивация к прочтению по мере продвижения по теме; насколько хорошо составлены введения и заключения.
-
Иногда редактор может даже проверять текст на фактические ошибки, убеждаться, что в тексте нет неточного упоминания терминов, замен одного термина другим.
-
Проверять оформление и грамматику.
Вам необязательно безоговорочно принимать все правки редактора, если они вам не нравятся — вы всегда можете попытаться аргументированно переубедить его.
Кстати, вы оставите редактору меньше работы, если перед сдачей текста сами проверите его по описанной выше схеме.
Не знаете, как пишется какое-то слово или где поставить запятую? Сверяйтесь с порталом «Грамота» или любым справочником под редакцией Розенталя.
А как вообще начать писать лучше? Для этого потребуется сначала почитать.
Научит писать в современном информационном стиле книга «Пиши, сокращай» Максима Ильяхова и Людмилы Сарычевой.
От канцелярита поможет избавиться старая, но нисколько не устаревшая книга Норы Галь «Слово живое и мёртвое».
Избежать стилистических ошибок помогут справочные пособия: «Практическая стилистика русского языка» Д. Э. Розенталя, «Справочник по русскому языку: правописание, произношение, литературная правка» Д. Э. Розенталя, Е. В. Джанджаковой, Н. П. Кабановой, «Практическая стилистика современного русского языка» Ю. А. Бельчикова.
Несколько неформальных советов автору:
Пишем — отдельно, редактируем — отдельно
Писать и редактировать — две разные задачи для мозга и, когда мы их смешиваем, он входит в режим многозадачности и начинает отвлекаться. Так что сначала пишем всё, что хотим сказать, и не смотрим на повторы мысли и стиль (вообще ни на что не смотрим, просто пишем). А когда довели мысль до конца, перечитываем, и начинаем сами себя редактировать.
Не обязательно действовать по плану, но лучше, чтобы он был
Часто эту штуку называют «синопсис» — краткое содержание текста. Оно хорошо помогает, если то, что вы собираетесь написать, занимает больше страницы. В маленьких текстах план скорее мешает. Перед тем, как взяться за написание чего бы то ни было, подумайте, как вы хотите структурировать материал: с чего начнёте, чем закончите, какие важные мысли хотите донести до читателя и куда их лучше поставить. План может выглядеть как список или схема — главное, чтобы вы разбирались, что там к чему. План поможет преодолеть «боязнь белого листа» и лучше уложить в голове материал.
Важно: план не вырублен в камне, он ваш помощник, а не прописная истина. Скорее всего, когда вы будете смотреть на готовый текст, вы поймёте, что от первоначального плана ничего не осталось, и это нормально.
Блин, короче
Мы стараемся уйти от канцелярщины и инфостиля. А начинать писать что-либо — сложно. Перед вами чистый лист и кажется, что впереди — куча работы. Чтобы стало немного легче, а ещё, чтобы избежать всяких прекрасных словечек типа «вышеуказанный», «нижеследующий», советуем начинать текст с «Блин, короче» (когда закончите, естественно, это нужно удалить, но, как мы уже говорили: «пишем — отдельно, редактируем — отдельно»). Согласитесь, после «блин, короче» вы вряд ли начнёте писать всякую канцелярщину — градус пафоса сразу понижается. После «блин, короче» пишем так, будто объясняем что-то приятелю. Читатели за такое поблагодарят. Однако постарайтесь не свалиться в совсем неформальный стиль.
Написал — перескажи
Точнее, перечитай вслух. Именно вслух, потому что так сразу понятно, где в тексте неудачные места. Запинаетесь при чтении? Бинго! Найдено слабое место, которое надо переписать. Не хватает дыхания, чтобы закончить предложение? Значит, надо разделять. Споткнулись? Возможно, где-то притаилось слишком короткое предложение — надо продлить.
Кажется, что получилась фигня — иди спать
Итак, вы закончили текст и решили сразу его перечитать. Это.Очень.Плохая.Идея. Если у вас не высоченная самооценка, скорее всего покажется, что вышла какая-то фигня. Что делать? Во-первых, не паниковать (то есть не удалять всё, что вы написали, без возможности восстановления). Во-вторых, отойти от компьютера минимум на пару часов, а ещё лучше — на ночь.
Не шутится — не шути
Выдавленный из себя юмор очень заметен. Хорошие шутки не любят, когда над ними очень сильно стараются. Если сомневаетесь, оставлять ли шутку — убирайте.