Один источник правды: почему копировать данные в документацию — плохая идея

Сережа Рис · 12 January 2026

Скопировал список студентов из базы в README.md.

На восьмой день данные разъехались.

Что случилось

У меня платформа для курсов. Студенты — в SQLite: имена, цели, прогресс.

Решил сделать README в папке когорты. Скопировал туда имена и цели. Открываешь папку — сразу видно кто есть кто. Красота.

Потом Аня обновила цели через интерфейс. База обновилась. README — нет.

Два источника. Разные данные. Какой правильный?

Дублирование = рассинхронизация Не вопрос “если”. Вопрос “когда”.

Один факт — одно место хранения. Остальные ссылаются или генерируются автоматически.

База данных (источник) → README генерируется → актуален

Примеры:

DRY применяют к коду, но к документации тоже работает. Дублирование — это долг. Платить придётся рассинхроном.

Не дублировать. Нужна информация — открой базу. Звучит радикально, но работает.

Ссылаться. В README пишешь «студенты: см. интерфейс» и даёшь ссылку. Указатель вместо копии.

Генерировать. Скрипт читает базу, обновляет README. Или GitHub Action при каждом коммите.

По-моему, второй вариант — самый реальный. Генерация требует поддержки, а “не дублировать” неудобно для быстрого доступа.

Если всё-таки выбрал автоматизацию:

markdown-autodocs — GitHub Action. Ставишь маркеры, указываешь источник — при коммите секция обновляется.

<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./data.json) -->
<!-- AUTO-GENERATED-CONTENT:END -->

mdat — CLI для шаблонов. Комментарии превращаются в контент.

Свой скрипт. Иногда 15 строк на Python проще универсального инструмента. У меня такой есть для статистики атомов — читает SQLite, пишет markdown.

Копируешь данные — автоматизируй. Ручное копирование устаревает к вечеру.

В корпорациях это Data Governance. В маленьких проектах — просто не плодить копии.

README удалил. Вместо него — ссылка на интерфейс.

Если понадобится красивый обзор в markdown — напишу скрипт. Но пока ссылки хватит.