Перейти до вмісту

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

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

документацію поставлено під власний лінтер

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

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

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

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

  • Блокнот, рука, планшет із затискачем
    Фото: Mohamed_hassan / Pixabay
  • Справи, папери, документи
    Фото: Tomasz_Mikolajczyk / Pixabay

Застосуйте цей досвід у своєму проєкті

Використайте «Підключила до документації окремий лінтер» як відправну точку для схожого завдання у вашій організації. Послуги, що стоять за цією роботою, доступні й для вашого проєкту. Хтось на вашому боці столу, коли підрядник, бюджет або архітектурне рішення потребують кваліфікованої оцінки.

Переглянути наші послуги Зв'язатися з нами

Дізнайтеся, що привело до результату

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

Переглянути наші послуги Зв'язатися з нами

Одна частина довшого переліку — і він увесь на цьому сайті.

Кожен запис написано однаково: ситуація, завдання, що ми зробили і що змінилося.

Переглянути весь перелік

Визначте потрібне покращення

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

Дивитися, скільки це коштує Зв'язатися з нами

Ваша документація тихо застаріває?

Запитайте про рішення в роботі «Підключила до документації окремий лінтер». Ви говоритимете з людьми, які можуть пояснити роботу й оцінити ваш проєкт.

Переглянути наші послуги
welcome@engineer.company +45 50 10 61 84 Копенгаген, Данія
QR-код сторінки «Підключила до документації окремий лінтер — ліміт рядків для кожного файлу, який можна лише знижувати, вимогу індексу та перевірку справжніх шляхів, — який знайшов шість із дев'яти планів, позначених виконаними, попри невідмічені пункти, і чотирнадцять завдань перевірки перед комітом, не згаданих у жодному документі.»
Візьміть цю сторінку із собоюhttps://advisory.engineer.company/uk/portfolio/put-the-documentation-under-its-own-linter/