Эти правила помогают последовательно редактировать модули курса. Общие требования к Markdown, метаданным и введению находятся в AGENTS.md.
Теория и практика
- Теоретический модуль должен самостоятельно объяснять понятия, связи, методы, условия их применения и критерии решений. Существенный для понимания материал нельзя оставлять только в практикуме.
- Практикум содержит задания, разборы ситуаций и рабочие шаблоны. Подробный чек-лист можно вынести туда, если в теории остаётся объяснение его назначения и основных областей проверки. Практикум не становится обязательным продолжением теории только потому, что расположен рядом.
- Результаты обучения и краткие формулы могут храниться в отдельных редакторских документах. Не нужно механически повторять их в модуле.
- Сокращая текст, проверять, не исчезли ли обоснование, важное условие, шаг метода или граница применимости. Длину текста нельзя считать самостоятельной целью правки.
Ход объяснения
- Каждый раздел отвечает на определённый вопрос. Сначала вводится предмет или проблема, затем объясняются нужные понятия, механизм и последствия для решения. Перечень терминов не заменяет связи между ними.
- Понятие вводится до того, как на нём строится рассуждение. Если подробное определение будет позже, при первом употреблении нужен хотя бы понятный контекст.
- Метод, модель или список вопросов появляются после объяснения ситуации, для которой они нужны. Пример располагается рядом с объясняемым положением и действительно показывает его работу; несколько однотипных примеров не нужны.
- Порядок разделов следует зависимости понятий. При правке читать весь раздел и соседние части: проверять переходы, повторы и места, где следствие появляется раньше причины.
- Введение задаёт предмет и проблему согласно AGENTS.md. Итоги соединяют главные выводы модуля, а не повторяют введение или оглавление.
Структура и форма
- Уровень заголовка отражает место темы в рассуждении. Части одной модели не должны выглядеть самостоятельными темами того же уровня; заголовок нужен, когда под ним есть отдельная мысль.
- Списки сохраняются, если пункты выражают разные условия, действия, причины или части решения. Не превращать их в абзац только ради сокращения числа списков. Таблица полезна для сопоставления вариантов, список — для последовательности или набора условий, связный текст — для объяснения причин.
- Блок кода нужен для кода, команд или данных, где важно сохранить формат. Определения, обычные вопросы и примеры изложения не требуют блока с пометкой
text. - Основное объяснение пишется по-русски. Принятый английский термин можно сохранить, пояснив при первом содержательном употреблении; при наличии ясного русского эквивалента смешение языков сокращается.
Точность и проверка
- Наблюдение, предположение о причине и установленная причина различаются. Не формулировать условное техническое решение как универсальное правило: указывать, когда оно помогает и по каким признакам это проверить.
- Если текст вводит метрику, называть измеряемую величину и нужные для её понимания границы: единицу или знаменатель, период, класс операций. Пример должен содержать именно те данные, которые заявлены в объяснении.
- Технические определения и сведения о поведении инструментов проверяются по первичным источникам. Ссылка стоит рядом с подтверждаемым утверждением. В разделе источников нужен видимый нумерованный список; после правки проверяются лишние и пропущенные источники, работоспособность ссылок и их отображение.
- После правки проверяются согласованность заголовков, терминов и примеров, локальные ссылки и
git diff --check. Правила сохраненияsource_idи создания новых файлов заданы в AGENTS.md.
