Підключила до документації окремий лінтер — ліміт рядків для кожного файлу, який можна лише знижувати, вимогу індексу та перевірку справжніх шляхів, — який знайшов шість із дев'яти планів, позначених виконаними, попри невідмічені пункти, і чотирнадцять завдань перевірки перед комітом, не згаданих у жодному документі.

Ситуація. Репозиторій живе за власними письмовими інструкціями — двадцятьма шістьма документами про політику якості, дизайн‑систему, доступність, друк, метадані, переклад і git. Інструкції старіють за характерним сценарієм: вони довшають, розходяться з кодом, починають посилатися на файли, які вже перемістили, а після певного обсягу їх перестають читати. Непрочитане правило — не правило.

Завдання. До документації треба було ставитися так само, як до коду, — тобто потрібен був лінтер з обмеженнями, які блокують, а не просто радять.

Дія. Вісім політик, і кожна перевіряється механічно. Жорстка межа довжини документа й м’якша, яка лише попереджає. Бюджет рядків для кожного файлу, який може лише зменшуватися, тож документ може скоротитися, але вже не виросте назад. Обов’язковий покажчик для документів, довших за певний поріг, і покажчик розділів — для довших за менший поріг. Правило розташування: яка тема належить якому документу. Справність посилань. Чесність планів: заявлений у плані статус має відповідати його власним прапорцям. Правило, за яким кожне завдання, що перевіряє коміт, має бути згадане в якомусь документі. І перевірка реальних шляхів: кожен шлях із зазначенням каталогу й кожен символ коду, згаданий у документі, мають справді існувати. Перший же запуск виправдав усю затію: шість планів, позначених як виконані, з невідміченими прапорцями, чотирнадцять завдань, які перевіряли кожен коміт, але не згадувалися в жодному документі, три биті посилання, один документ, на який ніщо не посилалося, і три шляхи в нікуди в п’яти документах. Згодом бюджет не пропустив навіть зміну від того, хто його запровадив: підсумок цієї роботи, дописаний до документа про розробку, вивів той за межу, — так і з’явився окремий документ, тобто політика спрацювала саме так, як задумано.

Результат. Двадцять шість документів загальним обсягом приблизно 2 666 змістовних рядків, кожен у межах бюджету, який не може зрости, а кожен згаданий у них шлях і символ звірено з деревом репозиторію. Незручний висновок варто повторити: чотирнадцять перевірок контролювали кожен коміт, але не згадувалися в жодному документі, тож правила, які застосовувала машина, і правила, які читали люди, вже розійшлися.