You might pretend to be insensible to adverts on websites, to turn off your brain when you see a box with an invitation to buy something. But like other humans, you can absorb messages and promotions by simply being exposed to them. You can read biased opinions online or posts written by poorly informed people and accept as true those words.

When you read about some technology new to you the official website is usually the primary source of information, the community might look nice and helpful and you soon will start to have an idea about the project.

But you also read the documentation and try the product, soon you realise you cannot do certain things and you have to read the source code for features that might look trivial. Then you read twice the same piece of the nicely written documentation and you start to think there is something wrong about your comprehension...or just think this product is junk and move over!

Everything in the documentation looks easy, simple and trivial in every scenarios. Sadly, as long as you go deeper you realise something is lacking, some fundamental feature is not documented, you look in the source code and find questions online written by people few years before with poor solutions. Your curiosity is now frustration.

I believe we have fallen in a trap made by the documentation writing style. Words like easy, simple and just are all over the place, reinforcing the ideas and usually the overconfidence of software developers. Someone noticed this trend and tried to explain the roots.

There is also another article worth reading.

The video mentions Laravel's documentation as an example of such writings, with a quick search on GitHub you can see how often the word easy is used and read the relative sentences.

I don't find such style offensive, but I consider the use of such words a clear weakness in writing skills, you shouldn't overuse them. This style will hurt your users in the medium and long term with frustration.

I found myself sometimes struggling with Laravel documentation, I'd like to read something more honest that can point you to the sources occasionally or admit that something needs to be explained better.

But this can hurt the popularity of the product and sometimes I feel the documentation is written like marketing material. Les Hatton wrote on The Chimera of Software Quality:

Software development isn't an engineering industry, it is a fashion industry populated by unquantifiable statements and driven by marketing needs.

This is still true, sometimes developers are just driven by hype and marketing, docs like that will shadow the good parts of the projects. Next time you read a piece of documentation for some new project, check for this writing style to not get tricked.