If you're stuck on a task, the last thing you want to hear is that it's really simple.

On the other hand, I would write that X is a simpler approach than Y, if I was comparing two possible approaches.

If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.

But it's a rhetorical question...

Feeling offended is a very different emotion than feeling alienated.

...yes it is? The word has multiple meanings.

> free from complexity or difficulty [https://www.merriam-webster.com/dictionary/simple]

> involving minimal difficulty or effort [https://www.merriam-webster.com/thesaurus/simple]

etc

Words should be used carefully or we end up with no word to say what we mean. That's why there's literally no word meaning what we want to say by "literally".

But from context you can determine whether "literally" means "literally" or "figuratively". It's the same with "simple", you should assume it means "simple" and not "easy" in the case of a documentation where words are chosen carefully.

No one is complaining about projects that say they're simple if they actually are simple and easy to use (i.e. download a binary, run the binary, it doesn't break and does the ~right thing). I think this is more a reaction to when people say "oh it's simple just <huge amount of setup> and you're done!", or even worse when they say "oh it's simple just download and run" and when you do that you're hit with an incomprehensible error/notation talking about deep internals you have to configure.

We've been told for years that it's demeaning to do the opposite and underestimate or over-explain, so people may have been erring too far in this direction.

We've also seen a lot of "the burden of communication lies on the communicator, not the listener," (quotes indicate paraphrasing) but this may also have led to overcorrection on the part of some listeners.

It's often impossible to predict what knowledge level and cultural background one's readers will have, so somehow we have to find a middle ground and ask that everyone mutually assume good faith and put in some effort to understand the other party, both when communicating and when reading.

Here is a tutorial I wrote:

https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest...

I tried to just link to anything that might require more info. If you know how to do it, great, don't click the link. Otherwise, what you need is right there.

If you always include at least a summary of what the user is expected to know, it lets the user read the documentation nonlinearly without getting completely lost when they hit an unfamiliar concept.

This way, when someone ignores the section and comes to me in incomprehension of a document they were not expected to understand, I can ask them what was unclear about the "About This Document" section. Although that's probably optimistic about how often people read documentation.

What I hate about this kind of bad documentation is that juat by spending an hour and writing down a few good examples and explaining them you could save hundreds of collective brain hours and maybe even improve adoption of your library if that is a relevant category for your project.

But more often than not you will find auto generated documentation where you see nothing on the first page, nothing explaining what that library can do, can't do, is intended to be used for, is not intended to be used for, some usage example how to get started etc.

Instead you will find a half page in some obscure class documentation that seems to be addressed to the dev themselves instead of to any outside audience.

What I mentioned above doesn't have to take long. You built the library. If you cannot write a simple example of how to use it within 5 minutes you probably should rewrite that library before publishing it. Integrate that example into your tests and now you even know when it will fail.

They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.

I'm not sure if this is just a front-end JS thing or if everyone is having this problem, but it seems like the majority of people writing docs aren't doing it to educate their users, they're doing it to proclaim to the world how smart they are with their revolutionary new tool that "makes foo simple" (and by that they mean makes foo easier* by adding complexity), and if the person reading it happens to learn something too that's just a bonus.

*until you colour slightly outside the lines and have to dive into whatever their shit library abstracted away anyway.

In such a context, it is reasonable to expect documentation to have a lower and upper bound on detail and scope they cover. It is not reasonable to expect all readers to know how to bridge over out of bounds detail and/or scope if they need to for their particular use case.

Examples of operative phrases to use are "for more detail on..." or "for more information on...", the former letting readers know how to obtain prerequisite knowledge, the latter letting readers know how to obtain out of bounds perspectives. Unfortunately, the art of systems-thinking-grade (wonderful link to Russell Ackoff's article on the front page today) technical writing has greatly atrophied in practically all organizations I have consulted for, and deteriorated to tactical-level documentation that reinforces a downward spiral in systems comprehension capabilities across organizations. This stems largely from a global leadership culture that applies the "simply" or "just" mentality to technical writing (which IMHO really should be called "systems writing" when it reaches a certain complexity to point out what we're really trying to accomplish at that arguably different use case, using technical writing as a tiny subset of its value delivery).

For me, "simply" and "just" are speed bumps in my reading. I notice them because they slow me down and serve no useful purpose in writing.

I don't think it's insulting my competence, it's just that "simple" is a sign that the original developer is not aware of the complexity (SNMP, anyone?) and hence it's now a trigger word for "prepare to be miserable for a while". And I don't like to feel miserable while dissecting something someone called "simple".

"Just" is a huge red-flag for me, not just in documentation, but also in effort estimation, requirements gathering, etc. It's the ??? between underpants gnomes and profit.