mt5-manager/docs/articles/style-notes.md

# Памятка по стилю статей (по текстам автора на mql5.com)

Составлена по полным текстам статей 19946, 19623 и 21323 и по фрагментам
14026, 15294, 19804, 19852. Служит ориентиром при подготовке новых частей
цикла. Это описание, а не образец для копирования: цитаты ниже короткие.

## Структура статьи

1. **Введение.** Подробный пересказ предыдущей части («В предыдущей части мы
   заложили фундамент…»), затем что будет сделано сейчас.
2. **«Намечаем путь».** Что нужно решить и в каком порядке, без кода.
3. **Шаги реализации.** Короткие заголовки из 2–4 слов («Новый маршрут»,
   «Схема работы с модулем», «Подопытные счета»).
4. **«Тестирование».** Как выглядит результат, со скриншотами («Рис. 1.»).
5. **«Заключение».** Что сделано и что дальше; последняя строка:
   «Спасибо за внимание и до новых встреч!»
6. **«Предупреждение»** (если уместно) и **«Содержание архива»** (таблица
   файлов с версиями и описанием).

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

## Голос и ритм

- Авторское «мы» вместе с читателем: «приступим», «давайте посмотрим»,
  «сохраним изменения в файле…». «Я» почти не бывает.
- Безличные обороты: «можно», «нужно», «стоит», «достаточно указать».
- Предложения средней и большой длины, с уточнениями через запятую и тире.
  Короткие фразы только как переходы или выводы: «Но обо всём по порядку.»,
  «Описание класса готово.», «Возможно, это неспроста.»
- Связки: «Итак», «Поэтому», «Однако», «Таким образом», «Кстати», «Теперь».
- Иногда вопрос, на который тут же даётся ответ.

## Смягчение

Частые слова и обороты: «вряд ли», «скорее всего», «в принципе», «по сути»,
«довольно», «пока что», «вполне допустимо», «примерно», «судя по всему».
Категоричные утверждения оставляем для установленных фактов (например,
для поведения функции по документации).

## Как объясняются решения

Сначала проблема или ограничение, затем решение, затем оценка альтернатив.
Мотив проговаривается: «на это есть вполне понятная причина», «так как».
Об ограничениях и неудачах пишется спокойно («К сожалению, на момент написания
установить модуль не удалось…», «в справке прямо не указано…»).

## Оформление

- При подготовке HTML для MQL5 перед каждым заголовком раздела добавляем
  один пустой абзац `<p>&nbsp;</p>`, чтобы отделить его от предыдущего текста.
  Такой же отступ нужен перед «Содержанием архива».
- Названия каталогов в таблице архива выделяем жирным единообразно.
- Основное содержимое абзацами. Маркированные списки редки; если есть, то
  короткие, с вводной фразой и двоеточием.
- Жирный шрифт почти не используется; термины и имена файлов выделяются
  курсивом или моноширинным шрифтом.
- Код блоками, комментарии в коде русские и по возможности нумерованные
  («# 1. Импорт модуля»).
- В MQL5 комментарии перед блоком начинаются с `//---`. На первом уровне тела
  функции они идут от левого края, на вложенных — по отступу описываемого блока.
  Комментарии `//` в конце строк выравниваются по колонке. У функций и обработчиков
  нужны непустые заголовки-рамки `//+---...---+` с названием или описанием.
- Ссылки на предыдущие части с номерами и гиперссылками: «в части 3»,
  «как мы делали совсем недавно».

## Чего избегать в нашем черновике

- Драматизации («коварная ошибка», «Важная оговорка», «Проговорим сразу»).
- Длинных списков с жирными заголовками пунктов.
- Уверенных формулировок там, где мы что-то не измеряли или не проверяли
  в документации.