Создание тем: написание и редактирование

Перед тем как писать

Прочитайте правила стиля и spec/conventions.md в корне репозитория.
Проверьте spec/structure.md в корне репозитория, чтобы увидеть, куда вписывается тема и какой номер ей положен.

Написание новой темы

Выберите часть и следующий свободный десятичный номер в этой части. Нумерация сплошная, поэтому новая тема обычно получает номер после последней темы своей части.
Создайте locales/en-gb-oxendict/topics/PP-CC-slug.md (префикс с ведущими нулями через дефис, например 02-01-...) из шаблона темы. Пишите в оксфордской орфографии (см. spec/oxford-spelling.md); никогда не правьте остальные три локали напрямую.
Пишите по шаблону. Содержательной теме нужны все разделы: обзор, ключевые принципы, рекомендации, компромиссы (с таблицей), вопросы для обсуждения, отраслевой взгляд (стартап, малый бизнес, крупное предприятие, государство), примеры (один из предприятия и один государственный), бизнес-кейс, антипаттерны, модель зрелости из пяти уровней, идеи для обсуждения, основные выводы и источники.
Назовите путь манипулирования. Каждому семейству метрик нужен явный ответ на вопрос «как команда может сделать это число хорошим, не улучшив то, что оно измеряет, и какая страховочная метрика это ловит» (см. тему 1.2).
Определяйте термины при первом употреблении. Добавляйте ссылку на Википедию для ключевых понятий при первом упоминании, только в прозе.
Делайте перекрёстные ссылки на связанные темы по десятичному номеру, например «(тема 2.1)».
Добавьте тему в spec/structure.md.
Если введение части (N.0) перечисляет её темы, добавьте пункт.
Запустите python3 tools/localize.py, чтобы вывести тему в en-001, en-gb и en-us.
Запустите just nav, затем just test.

Редактирование существующей темы

Сохраняйте порядок и заголовки разделов. Тесты проверяют, что в содержательных темах по-прежнему есть все обязательные разделы.
Сохраняйте встроенные определения, ссылки на Википедию, таблицы и списки источников, если правка не о них самих.
Не вносите длинные тире или запрещённые выражения. Если переформулируете, перепишите, а не вставляйте тире.
Затем запустите python3 tools/localize.py, чтобы заново вывести en-001, en-gb и en-us из отредактированного источника en-gb-oxendict.

Переименование или перенумерация

Переименуйте файл в locales/en-gb-oxendict/, обновите заголовок # N.M Title, обновите spec/structure.md и обновите все перекрёстные ссылки на старый номер.
Запустите python3 tools/localize.py, чтобы переименовать файлы и в остальных трёх локалях (он выводит все четыре из одного относительного пути).
Запустите just nav и just test. Тесты укажут на несовпадение H1 и имени файла, пропуск в нумерации, локаль, отошедшую от источника, или битую ссылку.

Напоминание о тоне

Пишите как опытный коллега, который хочет, чтобы читатель добился успеха. Тепло, просто, прямо и полезно. Короткие предложения. Без воды.