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», «как мы делали совсем недавно».

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

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