В корне и в docs/ накопилась документация, часть которой давно мимо кассы. Предлагаю пройти по
всему списку и разделить на «живое», «поправить» и «удалить».
Что явно лишнее
YAML_CHECKSUM_TEST_REPORT.md — отчёт о работе, сделанной 1 февраля в ветке
yaml-checksums-port, с указанием коммита c9b59763f. Это артефакт одной задачи, причём лежит
в корне репозитория. Место такому — в тикете или в описании PR, а не в дереве исходников.
docs/AFFECT_OFFLINE_TIMER_PLAN.md — план реализации #3678, с указанием ветки, от которой
он ответвлялся. План живёт до слияния; после — это история, и она уже есть в git.
Оба относятся к одному классу: рабочие артефакты, закоммиченные как документация. Их
неудобство не в занятом месте, а в том, что читатель не может отличить их от действующих
описаний — «отчёт» и «план» выглядят авторитетно, а описывают состояние полугодовой давности.
Что проверить на актуальность
| файл |
последняя правка |
tools/sqlite-world-schema.md |
21.01 |
tools/TESTING.md |
31.01 |
docs/YAML_MIGRATION_GUIDE.md |
21.06 |
Полгода без правок при том, что форматы мира за это время менялись (раскладка worlddata/
и userdata/, переход на YAML по умолчанию). Скорее всего описывают то, чего уже нет.
Отдельно: удвоение EN/RU
Пять руководств существуют в двух языковых версиях:
|
EN |
RU |
| COOKBOOK |
955 строк |
905 |
| SPELL_MANUAL |
1591 |
1508 |
| AFFECT_MANUAL |
578 |
602 |
| MECHANICS_MANUAL |
248 |
249 |
| FEAT_MANUAL |
299 |
308 |
Даты правок совпадают, то есть пары пока обновляют вместе, но объёмы разошлись на сотню строк.
Это ловушка на будущее: рано или поздно поправят одну версию и забудут вторую, а читатель не
узнает, какая свежее. Стоит решить осознанно — держим обе и следим, или оставляем одну.
Предложение по правилу
Чтобы это не накапливалось снова: отчёты о проделанной работе и планы реализации не коммитим
в репозиторий. Для них есть тикеты и описания PR, где они и остаются привязаны к своей задаче.
В дереве живёт только то, что описывает текущее состояние: руководства, справочники,
CONTRIBUTING.md, CLAUDE.md.
В корне и в
docs/накопилась документация, часть которой давно мимо кассы. Предлагаю пройти повсему списку и разделить на «живое», «поправить» и «удалить».
Что явно лишнее
YAML_CHECKSUM_TEST_REPORT.md— отчёт о работе, сделанной 1 февраля в веткеyaml-checksums-port, с указанием коммитаc9b59763f. Это артефакт одной задачи, причём лежитв корне репозитория. Место такому — в тикете или в описании PR, а не в дереве исходников.
docs/AFFECT_OFFLINE_TIMER_PLAN.md— план реализации #3678, с указанием ветки, от которойон ответвлялся. План живёт до слияния; после — это история, и она уже есть в git.
Оба относятся к одному классу: рабочие артефакты, закоммиченные как документация. Их
неудобство не в занятом месте, а в том, что читатель не может отличить их от действующих
описаний — «отчёт» и «план» выглядят авторитетно, а описывают состояние полугодовой давности.
Что проверить на актуальность
tools/sqlite-world-schema.mdtools/TESTING.mddocs/YAML_MIGRATION_GUIDE.mdПолгода без правок при том, что форматы мира за это время менялись (раскладка
worlddata/и
userdata/, переход на YAML по умолчанию). Скорее всего описывают то, чего уже нет.Отдельно: удвоение EN/RU
Пять руководств существуют в двух языковых версиях:
Даты правок совпадают, то есть пары пока обновляют вместе, но объёмы разошлись на сотню строк.
Это ловушка на будущее: рано или поздно поправят одну версию и забудут вторую, а читатель не
узнает, какая свежее. Стоит решить осознанно — держим обе и следим, или оставляем одну.
Предложение по правилу
Чтобы это не накапливалось снова: отчёты о проделанной работе и планы реализации не коммитим
в репозиторий. Для них есть тикеты и описания PR, где они и остаются привязаны к своей задаче.
В дереве живёт только то, что описывает текущее состояние: руководства, справочники,
CONTRIBUTING.md,CLAUDE.md.