9 ms·

This seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library aut

This seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library author says “makes X simple” they mean relative to existing ways of doing X. They don’t literally mean simple in absolute terms. The statement is useful because it immediately conveys the goal of the library.

gostsamo 5y ago
It is bad writing style as well. Streamlining the narrative in your tutorial and avoiding unnecessary words decreases the mental load of the reader.
tommica 5y ago
Personally, I don't find it insulting, but it does sometimes in a bad day help kick-starting the classic imposter syndrome of "I don't get it, oh no, I'm a fraud..."
hardwaresofton 5y ago
Right, except if the project didn't actually make the actual thing you want to get done Y (for which you were using X) simpler, but made it harder, because the docs for the new tool are nonexistent/obvious setup for the language/platform/framework produces an error, etc. 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.
MattGaiser 5y ago
The problem for me is that it over-estimates my competence. I often have no idea how to do simple thing X as required, so would appreciate a tutorial link or a more full explanation.
- nitrogen 5y ago
  The problem for me is that it over-estimates my competence. 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.
  - MattGaiser 5y ago
    My solution to that is just an abundance of links. Here is a tutorial I wrote: https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest-file-4bi9 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.
  - chousuke 5y ago
    I think good documentation should help the user build a mental model. Keep explanations to the point in general, but insert short reminders about previous concepts (with cross-references to s detailed explanation) to keep them in the reader's mind. Some redundancy in documentation is a plus. 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.
  - Kalium 5y ago
    I've found myself addressing the issue with a section at the top of documentation about the expected reader. I can get quite explicit about what the reader is expected to know, include links to relevant backgrounders, and warn that any reader who does not meet the requirements may have trouble. 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.
atoav 5y ago
I don't care if you call something simple, but I'd rather have you make it simple for me if you call it simple. Calling something simple can be a statement of fact ("objectively this thing is simpler than other comparable things") or it can be wishful thinking ("man this is really hard, better give them the motivation to wrap their head around it by taking away the edge"). The latter is what people tend to hate. It is "draw a circle, now draw the rest of the owl"-territory. 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.
- feoren 5y ago
  If you think writing down some good examples and explaining them takes "an hour", you have never written documentation. Writing good documentation takes forever!
  - atoav 5y ago
    Oh no worries I have written enough documentation. And you are right: writing good documentation is never done, because the thing you are documenting is never done and you can always fine tune the texts that you have written. 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.
yourapostasy 5y ago
In complex organizational environments managing complex technical landscapes, documentation using phrases that start with "simply..." are an indicator of insufficient technical writing fluency/structure/guidance/expectations. 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).
Aeolun 5y ago
Serverless claims to be simple. But they don’t add “if you are building a toy project”. Therefore, it would be better if they just didn’t say it was simple at all. They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.
- antonvs 5y ago
  Meh. If someone just blindly believes some marketing blurb and ignore the blitheringly obvious challenges, isn't that at least a little on them?
  - dwaltrip 5y ago
    Sure, perhaps. But people who make marketing content that contains bullshit or dishonesty shouldn’t get a free pass.
  - BigJono 5y ago
    The problem is that those marketing blurbs are never just on the front page these days, they're all through the documentation too. So I can't really fault people too much for falling for them. 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.
justin_oaks 5y ago
It's similar to hearing someone say "um" or "like" a lot. It doesn't bother you much until you notice it, then you can't help but notice it all the time. 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.
- edflsafoiewq 5y ago
  They convey relative difficulty. It's good to know what the simple operations are.
- thrwaeasddsaf 5y ago
  Basically.
bob_roberts 5y ago
Technical writer here. I avoid saying something is "simple," because whether it's simple is subjective and is relative to the reader's background knowledge. So at best it's unhelpful, and at worst it can be insulting. 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.
- thiht 5y ago
  Simple is the opposite of complex, not the opposite of hard. Saying something is simple has meaning, and it's not insulting.
  - Dashron 5y ago
    It's not a good feeling when you find something "simple" to be hard. Few tasks are easy when you're a new programmer still wrapping your head around conditionals. If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.
    - Kronen 5y ago
      The real question and a better post than the original post would be: Are people living in the 21st Century too easily offended? But it's a rhetorical question...
      - thiht 5y ago
        Yeah, maybe not being offended just because of the word "simple" would be a good start.
      - Dashron 5y ago
        I didn't use the word offended. Feeling offended is a very different emotion than feeling alienated.
  - lovegoblin 5y ago
yc-kraln 5y ago
Yeah, communication is just about explaining what someone should understand. It's a simple concept, and as a result you can be sure that you only need to type a document once, and it's immediately understood. In fact, just like your comment, there isn't any way to misinterpret vague language, or have to cater to someone for whom English isn't their first language. "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.
pronik 5y ago
I've used a lot of systems/libraries/etc. which claim to be "simple", but are really anything but. In many cases, "simple" equals to "primitive", which means that as soon as I move beyond the five-line example from the README I'm very likely to stumble upon a problem which will easily take a couple of days of furious googling, code-reading and issue-creating to get around. 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".

gostsamo 5y ago

It is bad writing style as well. Streamlining the narrative in your tutorial and avoiding unnecessary words decreases the mental load of the reader.

tommica 5y ago

Personally, I don't find it insulting, but it does sometimes in a bad day help kick-starting the classic imposter syndrome of "I don't get it, oh no, I'm a fraud..."

hardwaresofton 5y ago

Right, except if the project didn't actually make the actual thing you want to get done Y (for which you were using X) simpler, but made it harder, because the docs for the new tool are nonexistent/obvious setup for the language/platform/framework produces an error, etc. 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.

MattGaiser 5y ago

The problem for me is that it over-estimates my competence. I often have no idea how to do simple thing X as required, so would appreciate a tutorial link or a more full explanation.

nitrogen 5y ago
The problem for me is that it over-estimates my competence. 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.
- MattGaiser 5y ago
  My solution to that is just an abundance of links. Here is a tutorial I wrote: https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest-file-4bi9 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.
- chousuke 5y ago
  I think good documentation should help the user build a mental model. Keep explanations to the point in general, but insert short reminders about previous concepts (with cross-references to s detailed explanation) to keep them in the reader's mind. Some redundancy in documentation is a plus. 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.
- Kalium 5y ago
  I've found myself addressing the issue with a section at the top of documentation about the expected reader. I can get quite explicit about what the reader is expected to know, include links to relevant backgrounders, and warn that any reader who does not meet the requirements may have trouble. 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.

atoav 5y ago

I don't care if you call something simple, but I'd rather have you make it simple for me if you call it simple. Calling something simple can be a statement of fact ("objectively this thing is simpler than other comparable things") or it can be wishful thinking ("man this is really hard, better give them the motivation to wrap their head around it by taking away the edge"). The latter is what people tend to hate. It is "draw a circle, now draw the rest of the owl"-territory. 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.

feoren 5y ago
If you think writing down some good examples and explaining them takes "an hour", you have never written documentation. Writing good documentation takes forever!
- atoav 5y ago
  Oh no worries I have written enough documentation. And you are right: writing good documentation is never done, because the thing you are documenting is never done and you can always fine tune the texts that you have written. 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.

yourapostasy 5y ago

In complex organizational environments managing complex technical landscapes, documentation using phrases that start with "simply..." are an indicator of insufficient technical writing fluency/structure/guidance/expectations. 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).

Aeolun 5y ago

Serverless claims to be simple. But they don’t add “if you are building a toy project”. Therefore, it would be better if they just didn’t say it was simple at all. They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.

antonvs 5y ago
Meh. If someone just blindly believes some marketing blurb and ignore the blitheringly obvious challenges, isn't that at least a little on them?
- dwaltrip 5y ago
  Sure, perhaps. But people who make marketing content that contains bullshit or dishonesty shouldn’t get a free pass.
- BigJono 5y ago
  The problem is that those marketing blurbs are never just on the front page these days, they're all through the documentation too. So I can't really fault people too much for falling for them. 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.

justin_oaks 5y ago

It's similar to hearing someone say "um" or "like" a lot. It doesn't bother you much until you notice it, then you can't help but notice it all the time. 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.

edflsafoiewq 5y ago
They convey relative difficulty. It's good to know what the simple operations are.
thrwaeasddsaf 5y ago
Basically.

bob_roberts 5y ago

Technical writer here. I avoid saying something is "simple," because whether it's simple is subjective and is relative to the reader's background knowledge. So at best it's unhelpful, and at worst it can be insulting. 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.

thiht 5y ago
Simple is the opposite of complex, not the opposite of hard. Saying something is simple has meaning, and it's not insulting.
- Dashron 5y ago
  It's not a good feeling when you find something "simple" to be hard. Few tasks are easy when you're a new programmer still wrapping your head around conditionals. If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.
  - Kronen 5y ago
    The real question and a better post than the original post would be: Are people living in the 21st Century too easily offended? But it's a rhetorical question...
    - thiht 5y ago
      Yeah, maybe not being offended just because of the word "simple" would be a good start.
    - Dashron 5y ago
      I didn't use the word offended. Feeling offended is a very different emotion than feeling alienated.
- lovegoblin 5y ago

yc-kraln 5y ago

Yeah, communication is just about explaining what someone should understand. It's a simple concept, and as a result you can be sure that you only need to type a document once, and it's immediately understood. In fact, just like your comment, there isn't any way to misinterpret vague language, or have to cater to someone for whom English isn't their first language. "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.

pronik 5y ago

I've used a lot of systems/libraries/etc. which claim to be "simple", but are really anything but. In many cases, "simple" equals to "primitive", which means that as soon as I move beyond the five-line example from the README I'm very likely to stumble upon a problem which will easily take a couple of days of furious googling, code-reading and issue-creating to get around. 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".