Документація, яку хочеться читати! Але це не точно...

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

Раніше і я грішив цим: не було ні часу, ні мотивації розписувати очевидне.

Але не цього разу.

Зараз я і моя «команда молодая» розробляємо сервісоорієнтовану платформу для FMCG. Звісно, задач валом, і тому сайт для маркетингу ми робити не встигаємо, відтак (не з мого рішення) взяли підрядників. Сказали: ось ці хлопці робитимуть нам сайт на WordPress. І серед іншого — там має бути мультимовний каталог продукції з фасетними фільтрами.

Поспілкувавшись із WordPress-розробником, я зрозумів, що якщо він і витягне цю задачу, то зробить це десь за рік. Тому вирішив допомогти. Як же їм поталанило, що у нас вже є готовий мікросервіс catalog, побудований за EAV-патерном (Entity-Attribute-Value), де кожен параметр — це окремий об'єкт у структурі, і це одразу дає можливість будувати фасетні фільтри з коробки.

Коротше, надав йому API — замість того, щоб він пилив свою адмінку, фільтри, хостинг картинок тощо.

Для нас — ще один клієнт до додатку, для нього — купа зекономленого часу.

І підійшов я до цього з ентузіазмом: розписав максимально детальну API-документацію. І філософію, і особливості, і як краще підходити до інтеграції. Зробив обгортку над markdown, щоб генерувати сторінки як треба. Ось результат — мені не соромно виставити це на загал.

І що ви думаєте? Все, що було написано в блоках warning і attention, він проігнорував (чи просто не читав) — і по кожному кейсу потім писав мені:

“какая-то ашипка” “штото нє работаєт”

Поки я не розжував йому все персонально.

Мораль історії

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

А ще:

У вас тепер є майже унікальна можливість подивитися, як виглядає реально доступно написана документація API — по версії Доктора 😄

Вперше опубліковано в Telegram-каналі «Створений щоб помирати» 19.06.2025.