workshop-asciidoc

Workshop 'Creating documentation with the AsciiDoc'.

Process

1. Клонировать репозиторий.

2. Создать ветку согласно паттерну feature-${surname}, где ${surname} - фамилия на английском языке.

3. Создать документацию по теме (adoc + images):

   • создать директорию для темы или группы тем:

     • название должно соответствовать теме или группе тем;

     • название директории для изображений должно быть таким же;

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

   • выделить определения или важные термины жирным шрифтом;

   • выделить названия переменных, методов, значений как код;

   • удалить не существенный текст (например: "в следующей теме мы познакомимся с …​" и т.д.), т.е. текст который не помогает раскрыть текущую тему;

   • удалить личные местоимения;

   • дать названия для изображений, что бы они отражали суть того, что на них изображено;

   • добавить адекватный альтернативный текст для изображений;

   • заменить текст ссылающий на последующую таблицу/изображение/код/команду на заголовок к этому блоку (Block title).

4. Зафиксировать изменения в локальном репозитории.

5. Добавить ссылку на файл в index.adoc.

6. Зафиксировать изменения в локальном репозитории.

7. Удалить все файлы и ссылки связанные с примером:

   • документацию

   • изображение

   • ссылку в index.adoc

8. Зафиксировать изменения в локальном репозитории.

9. Загрузить изменения в удаленный репозиторий.

10. Создать запрос на слияние (PR/MR):

    • добавить всех членов команды как reviewer.

11. Получить необходимое количества подтверждений от команд:

    • если кто-то указал на ошибку, то исправить ее;

    • постоянно напоминать о необходимости провести ревью кода.

12. Делаем слияние feature ветки в develop:

    • если возник конфликт слияние, то решаем его.

13. Проверяем результат после deploy по соответствующей ссылке.

Note	Альтернативный текст - это текст, который будет отображен, когда изображение не сможет загрузиться

Mistakes

• Отсутствие отступа в одну строчку от заголовка:

  • Bad

=== Стилизация CSS
Стилизация элемента через *CSS* производится также, как и стилизация любого другого элемента.

• Good

=== Стилизация CSS

Стилизация элемента через *CSS* производится также, как и стилизация любого другого элемента.

• Избыточный отступ между элементами списка:

  • Bad

* `connectedCallback`: вызывается каждый раз, когда кастомный элемент html добавляется в DOM.

* `disconnectedCallback`: вызывается каждый раз, когда кастомный элемент html удаляется из DOM.

• Good

* `connectedCallback`: вызывается каждый раз, когда кастомный элемент html добавляется в DOM.
* `disconnectedCallback`: вызывается каждый раз, когда кастомный элемент html удаляется из DOM.

• Использование явного выделения для header таблицы

  • Bad

    |===
    |*PERCENTILE*
    |2
    |===

  • Good

    [options="header"]
    |===
    |PERCENTILE
    |2
    |===

• При упоминании функции/метода не использовать ()

  • Bad

    `PERCENTILE_DISC` — вычисляет определенный процентиль для отсортированных значений в наборе данных. В качестве параметра принимает процентиль, который необходимо вычислить.

  • Good

    `PERCENTILE_DISC()` — вычисляет определенный процентиль для отсортированных значений в наборе данных. В качестве параметра принимает процентиль, который необходимо вычислить.

• Выделение посторонних символов:

  • Bad

    *Деление:*

  • Good

    *Деление*:

• Некорректное выделение:

  • Bad

    `NaN (Not a Number)` // Not a Number - термин, NaN - исходный код
    `spread-оператор` // это термин, а не исходный код

  • Good

    `NaN` (*Not a Number*)
    *spread-оператор*

• Результат программы указывать в самой программе:

  • Bad

    var income = 100;
    var strIncome = "100";
    var result = income == strIncome;
    console.log(result); //true

  • Good

    var income = 100;
    var strIncome = "100";
    var result = income == strIncome;
    console.log(result);

    true

• Не экранировать символы, которые являются служебными для данного фреймворка

  • Bad

    <=

  • Good

    \<=

• Несоблюдение Code Convention для исходного кода

  • Bad

    var income = 100;
    var age = 19;
    if(income<150 && age>18){
    var message = "доход больше 50";
            alert(message);
    }

  • Good

    var income = 100;
    var age = 19;
    if (income < 150 && age > 18) {
        var message = "доход больше 50";
        alert(message);
    }

• Написание аббревиатур и имен собственных с маленькой буквы

  • Bad

    css, html, javascript

  • Good

    CSS, HTML, JavaScript

• Использование местоимений связанных с персоной или указывающих на принадлежность персоне

  • Bad

    `HEAD` – это указатель на коммит в вашем репозитории, который станет родителем следующего коммита.

  • Good

    `HEAD` – это указатель на коммит в репозитории, который станет родителем следующего коммита.

• Использование англицизмов вместо терминов на английском языке (есть исключения из этих правил, но для новых терминов ОДНОЗНАЧНО не следует использовать англицизмы)

  • Bad

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

  • Good

    Имеется широкий круг классов appenders, в том числе асинхронные appenders и appenders оборачивающие группу других appenders.

• Написание interfaces, classes и т.д. в одном блоке кода

  • Bad

    [source,java]
    ----
    interface A {
        default void showDefault() {
            System.out.println("A: default method show()");
        }
    }
    // ...
    public class B {
        public void showDefault() {
            System.out.println("B: method show()");
        }
    }
    ----

  • Good

    [source,java]
    ----
    interface A {
        default void showDefault() {
            System.out.println("A: default method show()");
        }
    }
    ----

    [source,java]
    ----
    public class B {
        public void showDefault() {
            System.out.println("B: method show()");
        }
    }
    ----