← Documentation you want to read! Or maybe not...
docs: English JsonRpcBundle docs, REST and MCP Bundle sections, package cards
en/articles/from-tg/architecture/documentation.md
new file +36
−0
1
+
# Documentation you want to read! Or maybe not...
2
+
3
+
Documentation is usually a sore subject in many companies. Often because it's either never written, or written "just to have it", or in general phrases because "it's obvious anyway".
4
+
5
+
I used to be guilty of this too: there was neither the time nor the motivation to spell out the obvious.
6
+
7
+
But not this time.
8
+
9
+
Right now my **"young team"** and I are developing a service-oriented platform for FMCG. Of course, there's a ton of tasks, so we don't have time to build a marketing website, and therefore (not my decision) contractors were hired. We were told: these guys will build us a WordPress site. And among other things, it has to include a multilingual product catalog with faceted filters.
10
+
11
+
After talking to the WordPress developer, I realized that even if he could pull this task off, it would take him about a year. So I decided to help. How lucky they were that we already had a ready-made catalog microservice built on the EAV pattern (Entity-Attribute-Value), where every parameter is a separate object in the structure, which right away makes it possible to build faceted filters out of the box.
12
+
13
+
Long story short, I gave him an API — instead of him building his own admin panel, filters, image hosting and so on.
14
+
15
+
For us — one more client of the application, for him — a ton of saved time.
16
+
17
+
And I approached it with enthusiasm: I wrote the most detailed API documentation possible. The philosophy, the specifics, and how best to approach the integration. I built a wrapper over markdown to generate the pages the way I needed. Here's [the result](http://bit.ly/44epXlF) — I'm not ashamed to put it out in public.
18
+
19
+
And what do you think? Everything written in the warning and attention blocks he ignored (or just didn't read) — and for every single case he later wrote to me:
20
+
21
+
> "some kinda errorr"
22
+
> "somethin aint workin"
23
+
24
+
Until I chewed it all over for him personally.
25
+
26
+
## The moral of the story
27
+
28
+
> No matter how much time you spend making something clear, there will always be someone who ignores it.
29
+
30
+
And also:
31
+
32
+
> You now have an almost unique opportunity to see what truly accessible API documentation looks like — according to the Doctor 😄
33
+
34
+
---
35
+
36
+
*First published in Ukrainian in the Telegram channel [“Created to die”](https://t.me/php_while_true/9) on June 19, 2025.*