The wrong simple

Last week while looking for a possible library to make my life easier with a potential switch from a custom REST API to the JSON:API format I encountered two problems.

The first one was that JSON:API is a bad naming for a standard to search. Newer APIs are most of the time in JSON format (but not the JSON:API one). When searching for it, you might guess, you'll find not only useful things.

The second and title giving one was the advertised simplicity of adopting the found libraries. I found three potential ones and all had the clause "Then simply add..." included in their readme. Also all of them had no deep dive, example apps or sufficient documentation about other (maybe not so "simple") ways to integrate. Additionally the given examples relied on an older version of the Phoenix framework that since has evolved in especially the area of view and the docs do not make sense in that regard anymore.

I remember having read posts about terms you should avoid when writing technical documentation and back then I thought it might be a little bit over the top. On the other hand the examples don't get easier to grasp when these little words are absent. To keep documentation up to date is very hard. Same category as code comments.