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

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

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

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

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

Категорії:
1Автоматизація та CI/CD	/uk/categories/automation/	engineer.company	70
1Тестування та QA	/uk/categories/testing/	engineer.company	70
1Python	/uk/categories/python/	engineer.company	70
1Технічне лідерство	/uk/categories/technical-leadership/	engineer.company	70
1Управління проєктами	/uk/categories/project-management/	engineer.company	70
1Документація	/uk/categories/documentation/	engineer.company	70

Послуги:
1Технічне лідерство та консалтинг	/uk/services/technical-leadership/	engineer.company	70
1Управління проєктами (Agile)	/uk/services/project-management/	engineer.company	70
1Технічна документація	/uk/services/technical-documentation/	engineer.company	70

hЦя сторінка у вебі	URL:https://engineer.company/uk/portfolio/put-the-documentation-under-its-own-linter/	engineer.company	70
