Перейти до вмісту
Engineer
Меню
Дизайн
Українська

Engineer / Портфоліо

Підключила до документації окремий лінтер

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

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

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

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

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

Контакти

Ще визначаєтесь, що саме вам потрібно?

Розкажіть, що йде не так або що ви намагаєтесь побудувати. Ми скажемо, що для цього потрібно, скільки це приблизно коштуватиме і чи ми ті люди, які вам потрібні.

Від 1 400 DKK за годину, без ПДВ — і дешевша година на довшому замовленні.

welcome@engineer.company +45 50 10 61 84 Копенгаген, Данія