Skip to content

Latest commit

 

History

History
123 lines (89 loc) · 9.88 KB

README.md

File metadata and controls

123 lines (89 loc) · 9.88 KB
Raw

Контакт для связи: 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), если это возможно, и альтернативным текстом. Пример (при использовании убрать '\'): [![JDK SETUP](http://img.youtube.com/vi/uXMTq81jG7Y/0.jpg)](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: Какая-то информация.

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

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

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

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