← Документація, яку хочеться читати! Але це не точно...
docs: English JsonRpcBundle docs, REST and MCP Bundle sections, package cards
uk/articles/from-tg/architecture/documentation.md
новий файл +36
−0
1
+
# Документація, яку хочеться читати! Але це не точно...
2
+
3
+
Зазвичай тема документації — це болюча тема в багатьох компаніях. Часто тому, що її або ніколи не пишуть, або пишуть «щоб було», або загальними фразами, тому що «і так зрозуміло».
4
+
5
+
Раніше і я грішив цим: не було ні часу, ні мотивації розписувати очевидне.
6
+
7
+
Але не цього разу.
8
+
9
+
Зараз я і моя **«команда молодая»** розробляємо сервісоорієнтовану платформу для FMCG. Звісно, задач валом, і тому сайт для маркетингу ми робити не встигаємо, відтак (не з мого рішення) взяли підрядників. Сказали: ось ці хлопці робитимуть нам сайт на WordPress. І серед іншого — там має бути мультимовний каталог продукції з фасетними фільтрами.
10
+
11
+
Поспілкувавшись із WordPress-розробником, я зрозумів, що якщо він і витягне цю задачу, то зробить це десь за рік. Тому вирішив допомогти. Як же їм поталанило, що у нас вже є готовий мікросервіс catalog, побудований за EAV-патерном (Entity-Attribute-Value), де кожен параметр — це окремий об'єкт у структурі, і це одразу дає можливість будувати фасетні фільтри з коробки.
12
+
13
+
Коротше, надав йому API — замість того, щоб він пилив свою адмінку, фільтри, хостинг картинок тощо.
14
+
15
+
Для нас — ще один клієнт до додатку, для нього — купа зекономленого часу.
16
+
17
+
І підійшов я до цього з ентузіазмом: розписав максимально детальну API-документацію. І філософію, і особливості, і як краще підходити до інтеграції. Зробив обгортку над markdown, щоб генерувати сторінки як треба. Ось [результат](http://bit.ly/44epXlF) — мені не соромно виставити це на загал.
18
+
19
+
І що ви думаєте? Все, що було написано в блоках warning і attention, він проігнорував (чи просто не читав) — і по кожному кейсу потім писав мені:
20
+
21
+
> “какая-то ашипка”
22
+
> “штото нє работаєт”
23
+
24
+
Поки я не розжував йому все персонально.
25
+
26
+
## Мораль історії
27
+
28
+
> Скільки б часу ти не витратив на те, щоб зробити щось зрозумілим — знайдеться той, хто це проігнорує.
29
+
30
+
А ще:
31
+
32
+
> У вас тепер є майже унікальна можливість подивитися, як виглядає реально доступно написана документація API — по версії Доктора 😄
33
+
34
+
---
35
+
36
+
*Вперше опубліковано в Telegram-каналі [«Створений щоб помирати»](https://t.me/php_while_true/9) 19.06.2025.*