Контакт для связи: Telegram

Ссылка на канал: Дорогу осилит идущий

Заметка для контрибьюторов

Если вы хотите помочь в переносе статей из telegra.ph в репозиторий, эта памятка для вас:

1. Сделайте fork репозитория;
2. Подготовьте переносимый урок в формате md-файла. Требования к оформлению можно найти ниже;
3. Сделайте PR на master основного репозитория;
4. В сообщении к PR укажите Номер урока в Road Map и, опционально его тему;
5. Напишите мне в ЛС со ссылкой на PR или укажите контакт для связи в описании к PR;
6. Дальнейшая коммуникация и правки по замечаниям в личном порядке.

Повторяйте пункты 2-6 для каждого PR.

Важно: не добавляйте в один PR несколько уроков. Это как затруднит, так и затянет процесс обработки PR.

Искренняя благодарность каждому, кто поможет в этом муторном процессе❤️

Требования к оформлению статьи

Расположение урока и именование

• Каждый урок должен располагаться в своем разделе в соответствии с Road Map. Если раздел не существует - вы можете его создать самостоятельно;
• При добавлении раздела его имя указывается на английском, слова разделяются дефисами: chapter-name
• Для каждого урока внутри раздела создается директория с номером урока в Road Map. Нумерация сквозная;
• Название md-файла должно содержать название урока на английском. Допустимо использовать пробелы и знаки препинания. Допустимо упрощение названия от оригинального для большей лаконичности. Пример: How to name lesson.md;
• md-файл урока помещается в директорию урока. В итоге путь к нему должен выглядеть примерно так: ${projectHome}/lessons/chapter-name/666/your-file.md.

Исходный md-файл

• Длина строки не должна превышать 120 символов;
• Заголовки и другие элементы, отличные по оформлению от обычного текста должны быть отделены пустой строкой. Рекомендую настроить форматирование по приложенной схеме (можно применить к IDEA и другим продуктам JetBrains): ссылка

Изображения и медиа

• Изображения, используемые сугубо в рамках урока (схемы и другие иллюстрации) должны лежать в директории урока;
• Если изображение используется многократно (футеры "На сегодня все"), оно должно лежать в директории ${projectHome}/commonmedia;
• В md-файле используются только относительные ссылки на изображение;
• Название изображения должно быть на английском. Должно быть осмысленным и указано в camelCase: collectionHierarchy.png;
• Ссылки на видео-материалы оформляются через URL на внешний ресурс с превью в виде изображения (через внешний URL), если это возможно, и альтернативным текстом. Пример (при использовании убрать '\'): [](http://www.youtube.com/watch?v=uXMTq81jG7Y)

Заголовки

• Тема урока обозначается как заголовок уровня H1:

'# Тема'

• Дальнейшие подпункты, в зависимости от уровня, обозначаются заголовками уровня H2-H4, в соответствии с оригинальной структурой. Заголовок H3 может идти исключительно как подпункт заголовка H2. H4 - только как подпункт H3. При сомнениях - помечайте подобные места собственными замечаниями к PR.

'## Пункт урока'

'### Подпункт урока'

'#### Наименьший из возможных подпунктов. Вроде бы не использовался в переносимых статьях.'

Оформление кода

• Вставки названий переменных, классов, методов и других элементов кода в обычном тексте должны быть оформлены как код: someVarName, someMethodName();
• При указании методов в тексте, они всегда должны содержать скобки. Параметры можно опустить или записать в упрощенном виде зависимости от контекста: equals(), equals(Object);
• При указании отношения конкретного метода к конкретному классу в обычном тексте должны использоваться следующие обозначения:
  • ClassName.methodName() - для статических методов. Параметры могут быть опущены или описаны в упрощенной форме, если контекст это позволяет;
  • ClassName#methodName() - для не статических методов. В старых статьях обычно использовался символ ':' вместо '#', но от этой практики стоит уйти.
• При описании SQL в обычном тексте все операторы должны указываться в UPPER_CASE: SELECT;
• Фрагменты кода вне обычного текста и любой связный код должен оформляться соответствующе:

/**
 * Something code
 */

• Если возможно, в блоке кода должен быть указан язык для подсветки синтаксиса. Кроме случаев использования псевдокода;
• При использовании SQL в блоке кода допустима запись в нижнем регистре. В т.ч. для операторов;
• При использовании названий сущностей или методов на русском (в качестве примеров, для прозрачности условия практики и т.д.) используется курсив. При этом имена сущностей указываются с большой буквы, для методов указываются скобки: "...создайте сущность Машина", "... используйте метод1()".*

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

Bold текст

• Полужирным выделяются новые термины при их первом упоминании;
• Опционально, термины могут выделяться полужирным второй раз в месте, где дается определение ранее упомянутому термину.

Цитаты

Использование цитат оправдано в следующих случаях:

1. Сноски, обозначенные через '*'. При этом в цитате тоже указывается '*'. Проверяйте, чтобы отображался именно указанный символ, а не символ ненумерованного списка;
2. NB (Nota bene) блоки. Форма записи следующая:

!NB: Какая-то информация.

3. Побочная информация, вроде отсылок к практике или примерам из опыта.
4. Футер с контактами

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

Заключительные шаги

После мержа вашего PR, проверьте, что в Road Map была скорректирована ссылка на урок - это будет ответственность ревьюера, но проверить за ним можете и вы:)