Documentation you want to read! Or maybe not...

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".

I used to be guilty of this too: there was neither the time nor the motivation to spell out the obvious.

But not this time.

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.

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.

Long story short, I gave him an API — instead of him building his own admin panel, filters, image hosting and so on.

For us — one more client of the application, for him — a ton of saved time.

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 — I'm not ashamed to put it out in public.

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:

"some kinda errorr" "somethin aint workin"

Until I chewed it all over for him personally.

The moral of the story

No matter how much time you spend making something clear, there will always be someone who ignores it.

And also:

You now have an almost unique opportunity to see what truly accessible API documentation looks like — according to the Doctor 😄

First published in Ukrainian in the Telegram channel “Created to die” on June 19, 2025.