CONTRIBUTING.md

Руководство по редактированию учебника

В этом файле находится вся необходимая информация, которая может понадобиться при редактировании учебника.

Оглавление

1. Добавление материалов в русскую версию учебника и перевод материалов из английской версии
2. Структура учебника
3. Запуск учебника локально
4. Как внести правки в учебник?
5. Как переводить материалы из английской версии учебника?
6. Как добавить строку кода?
7. Как добавить блок кода?
8. Как добавить информационный блок?
9. Как добавить предупреждающий блок?
10. Как добавить блок «Новая возможность»?
11. Как добавить ссылку на другую статью из учебника?
12. Как добавить изображение в статью или задачу?
13. Как добавить клавишу в текст?

---

Добавление материалов в русскую версию учебника и перевод материалов из английской версии

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

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

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

Хотите добавить новую статью в русскую версию? Дополнить какую-либо из статей новой информацией? Без проблем. Единственное условие — по возможности, отправьте перевод новых материалов и в английскую версию, если знаете язык.

• Структура учебника
• Запуск учебника локально
• Как внести правки в учебник?
• Как переводить материалы из английской версии учебника?
• Перед тем, как делать какие-либо масштабные правки по типу добавления новой статьи, обязательно обсудите эту идею, открыв Issue в категории «Предложить идею по улучшению материала учебника»

Несколько деталей

• Вы и его производные пишите с маленькой буквы
• Всегда используйте букву ё (этот npm-пакет может проверить текст и вставить её, где нужно)
• Не знаете, как перевести английский термин? Словарь «Веб-стандартов» поможет!
• Названия компаний (Google), библиотек (Jest) и аббревиатуры (DOM) не переводятся.
• importance: n встречающееся в начале задач - служебное поле, перевод не требуется.

Ресурсы по переводу

Чтобы улучшить ваш перевод и, вообще, письмо, полезные статьи:

• Берегись канцелярита!
• Словесная алгебра
• Поиск переводов в контексте
• DeepL - переводчик на нейросетях

---

Структура учебника

Если вы планируете внести правки в одну статью (или в одну задачу), углубленное понимание структуры учебника вам не понадобится.
Можете сразу переходить к делу: «Как внести правки в учебник?»

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

---

Каждому разделу, статье или задаче соответствует директория.

Эта директория имеет вид N-url, где N - это номер для сортировки статей и разделов (они упорядочены), а url – URL-имя, по которому материал будет доступен.

В директории 1-js находятся все разделы из первой части учебника («Введение», «Основы JavaScript», ... ).
Каждая директория в 1-js — это раздел:

• Директория 01-getting-started => Раздел «Введение»
• Директория 02-first-steps => Раздел «Основы JavaScript»
• и так далее... (по названиям директорий можно интуитивно догадаться, что это за раздел)

В этих директориях содержатся все статьи конкретного раздела (каждой статье соответствует определенная директория): для примера возьмём раздел «Введение» (директория 01-getting-started). В разделе «Введение» 4 статьи. Вот как это выглядит в Github:

В директории 01-getting-started:

• Директория 1-intro => Статья «Введение в Javascript»

• Директория 2-manuals-specifications => Статья «Справочники и спецификации»

• Директория 3-code-editors => Статья «Редакторы кода»

• Директория 4-devtools => Статья «Консоль разработчика»

• index.md => файл, который находится в каждом разделе. В нём содержится название и описание конкретного раздела.

  

Вот структура файлов в директории каждой статьи:

Обратите внимание: 1) не в каждой статье есть задачи 2) не в каждой задаче есть интерактивная демонстрация

В директории 2-ui находятся все разделы со статьями из второй части учебника («Документ», «Введение в события», ... ).
Структура такая же, как описано выше.

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

• Директория 3-frames-and-windows => Раздел «Фреймы и окна»
• Директория 4-binary => Раздел «Бинарные данные и файлы»
• Директория 5-network => Раздел «Сетевые запросы»
• Директория 6-data-storage => Раздел «Хранение данных в браузере»
• Директория 7-animation => Раздел «Анимация»
• Директория 8-web-components => Раздел «Веб-компоненты»
• Директория 9-regular-expressions => Раздел «Регулярные выражения»
• Директория 20-css-for-js => Раздел «CSS для JavaScript-разработчика»

99-archive — архив устаревших статей.
В данной директории находятся статьи, которые по той или иной причине утратили свою актуальность. Эти статьи скрыты из оглавления сайта учебника. В репозитории английской версии учебника данного архива нет.

---

Запуск учебника локально

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

Сервер для этого находится здесь: https://github.com/javascript-tutorial/server.

В README.md находится инструкция по запуску сервера.

---

Как внести правки в учебник?

Если вы хотите отредактировать только одну статью/задачу

1. Откройте статью, которую собираетесь редактировать. Нажмите «Редактировать на Github»:

   

2. Выберите необходимый файл:

   

   Обратите внимание: 1) не в каждой статье есть задачи 2) не в каждой задаче есть интерактивная демонстрация

3. Нажмите на «✏»:

   

   После чего выберите «Fork this repository»:

   

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

4. Отредактируйте файл. Далее следуйте указаниям на картинке ниже (согласно нумерации):

   

5. Нажмите «Create pull request»:

   

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

   

   Вы отправили правки на рассмотрение. Теперь остаётся только внимательно следить за уведомлениями на Github.

Если вы хотите отредактировать сразу несколько статей/задач или добавить новую статью/задачу (перед этим обязательно создайте Issue в категории «Предложить идею по улучшению материала учебника»)

1. Откройте репозиторий учебника. Нажмите на «Fork»:

   

2. Нажмите «Create fork»:

   

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

3. Выберите необходимый файл согласно структуре учебника (или создайте его, если добавляете новую статью/задачу). После чего нажмите на «✏»:

   

4. Отредактируйте файл. Далее следуйте указаниям на картинке ниже (согласно нумерации):

   

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

5. Как закончите редактировать файлы, перейдите на страницу созданной вами копии учебника. Далее следуйте указаниям на картинке ниже (согласно нумерации):

   

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

   

   Вы отправили правки на рассмотрение. Теперь остаётся только внимательно следить за увемодлениями на Github.

Если вы — опытный пользователь Github, можете использовать Github Desktop или git для внесения правок. Выше описаны самые простые способы, подходящие для новичков.

---

Как переводить материалы из английской версии учебника?

Перевод не обязательно должен быть слово-в-слово. Он должен быть без ошибок и, по сути, верным, хорошо объясняющим.

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

Текст в коде

• Комментарии в коде – переводить.
• Строки в примерах – можно переводить, но не обязательно.
• Названия переменных, классы, идентификаторы – не надо переводить.

Например:

// Example
const text = "Hello, world";
document.querySelector('.hello').innerHTML = text;

✅ ХОРОШО (переведён комментарий):

// Пример
const text = 'Hello, world';
document.querySelector('.hello').innerHTML = text;

✅ ТОЖЕ ОК (переведён комментарий и текст):

// Пример
const text = 'Привет, мир';
document.querySelector('.hello').innerHTML = text;

Внешние ссылки

Если есть внешняя ссылка на MDN или Wikipedia, например https://en.wikipedia.org/wiki/JavaScript, но есть версия этой же статьи на русском, поменяйте ссылку.

Например:

[JavaScript](https://en.wikipedia.org/wiki/JavaScript) is a programming language.

✅ ПОСЛЕ ЗАМЕНЫ (en -> ru):

[JavaScript](https://ru.wikipedia.org/wiki/JavaScript) – это язык программирования.

Если статья на MDN переведена частично, это тоже подходит.

В случае, если у ссылки нет эквивалента на русском, оставьте её как есть.

Соглашение по переводу (глоссарий)

Пожалуйста, поддерживайте глоссарий в алфавитном порядке.

Оригинальный термин	Перевод
Arrow function	Стрелочная функция
Backtick	Обратная кавычка
Bitwise operator	Побитовый оператор
Breakpoint	Точка останова
Character class	Символьный класс
Comparison	Операция сравнения
Construct	Конструкция
Conversion	Конвертирование
Functionality	Функциональность
Left click/right click	Левый/правый клик? Кликните? левой кнопкой мыши
More in / Details in	Подробнее в
Nullish coalescing operator	Оператор нулевого слияния
Script	Скрипт
“Short-circuit” evaluation	Сокращённое вычисление
Statement	Инструкция
Summary	Итого

Ресурсы по переводу

Чтобы улучшить ваш перевод и, вообще, письмо, полезные статьи:

• Берегись канцелярита!
• Словесная алгебра
• Поиск переводов в контексте
• DeepL - переводчик на нейросетях

Несколько деталей

• Вы и его производные пишите с маленькой буквы
• Всегда используйте букву ё (этот npm-пакет может проверить текст и вставить её, где нужно)
• Не знаете, как перевести английский термин? Словарь «Веб-стандартов» поможет!
• Названия компаний (Google), библиотек (Jest) и аббревиатуры (DOM) не переводятся.
• importance: n встречающееся в начале задач - служебное поле, перевод не требуется.

---

Как добавить строку кода?

`// ... код ... //`

---

Как добавить блок кода?

JavaScript:

```js
// ... код ... //
```

HTML:

```html
// ... код ... //
```

CSS:

```css
// ... код ... //
```

Если блок кода находится внутри информационного/предупреждающего блока, нужно использовать 4 обратных кавычки `:

````smart header="Информационный блок"

```js
// ... код ... //
```

````

Чтобы добавить кнопки в правый верхний угол блока кода, нужно добавить run:

```js run
// ... код ... //
```

Чтобы JS-код запускался в нестрогом режиме, нужно добавить no-strict (по умолчанию все блоки кода запускаются с использованием строгого режима "use strict"):

```js run no-strict
// ... код ... //
```

Чтобы отключить подсветку синтаксиса в блоке кода, нужно добавить no-beautify:

```js no-beautify
// ... код ... //
```

Ключевые слова run, no-strict, no-beautify можно комбинировать:

```js run no-strict no-beautify
// ... код ... //
```

Чтобы выделить определенную часть кода, нужно поместить её в *!* */!*:

let year = prompt('В каком году была опубликована спецификация ECMAScript-2015?', '');

*!*
if (year == 2015) alert( 'Вы правы!' );
*/!*

Также *!* */!* можно использовать в одной строке:

let user = {
  name: "John",
  go: function() { alert(this.name) }
}*!*;*/!*

(user.go)() // John

---

Как добавить информационный блок?

```smart header="Название информационного блока"

Текст

```

Если внутри информационного блока находятся блоки кода, нужно использовать 4 обратных кавычки `:

````smart header="Название информационного блока"

```js
// ... код ... //
```

````

Если в названии информационного блока находятся двойные кавычки ", их нужно экранировать (\"):

````smart header="\"Название\""

Текст

````

---

Как добавить предупреждающий блок?

```warn header="Название предупреждающего блока"

Текст

```

Если внутри предупреждающего блока находятся блоки кода, нужно использовать 4 обратных кавычки `:

````warn header="Название предупреждающего блока"

```js
// ... код ... //
```

````

Если в названии предупреждающего блока находятся двойные кавычки ", их нужно экранировать (\"):

````warn header="\"Название\""

Текст

````

---

Как добавить блок «Новая возможность»?

[recent browser="new"]

Если нужно добавить блок «Новая возможность» со ссылкой на ресурс «caniuse.com»:

[recent caniuse="ключевое_слово_для_поиска_на_caniuse"]

---

Как добавить ссылку на другую статью из учебника?

- (У них также нет `super`, но мы про это не говорили. Про это будет в главе <info:class-inheritance>).

В <info: ... > указывается название, по которому статья будет доступна в учебнике.

Это название можно найти в Github:

...Или в адресной строке браузера:

---

Как добавить изображение в статью или задачу?

1. Загрузите изображение в директорию со статьёй (или в директорию с задачей)

2. Добавьте изображение в определённой части article.md (или task.md/solution.md, если добавляете изображение в условие/решение задачи):

   ![](название_изображения.png)
   

---

Как добавить клавишу в текст?

Обычно при нажатии `key:Enter` введённая строка кода сразу выполняется.