Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

If someone’s having to read your docs, it’s not “simple”

justsimply.dev

Post reply on HN
Print view View original

81–90 of 146 posts

Re: If someone’s having to read your docs, it’s not “simple”

#81

Post by chrismcb »

csande17 wrote: post #28

Is it just me, or does this change in particular totally destroy the meaning of the sentence? Original: > Mailers are really just another way to render a view. "Edited": > Mailers are another way to render a view. The original sentence suggests that, while mailers may look different, they use the same underlying "render a view" mechanism (as some other part of Rails, presumably). The revised version makes it sound li…

No, the first sentence does not imply that mailers use the same underlying "render a view" mechanism. I would argue it implies the exact opposite, in the mailers are just another way to render the view. The two sentences mean the same thing.

Re: If someone’s having to read your docs, it’s not “simple”

#82

Post by aspaviento »

MattGaiser wrote: post #44
an_opabinia wrote: post #40

Earlier quoted context omitted.

Someone who solves problems by Googling is a good customer. Someone who needs handholding or is unsophisticated is a bad customer. For developer tools and such, an educated person’s game, the sophisticated players will have better LTV than the unsophisticated ones.

The problem with many more niche things is that it hasn't gotten to the point where decent answers have accumulated on Google. I recently had to build a Word Add-In. Not a lot of those built at the moment. So we were dependent on the documentation, which while reasonably comprehensive, had some frustrating gaps in just getting the tutorial code running that took days to resolve.

OfficeJS Add-In or the old one?

Re: If someone’s having to read your docs, it’s not “simple”

#83

Post by pistoriusp »

vmception wrote: post #72
pistoriusp wrote: post #67

As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.

I interview people based on their ability to cheat on the assessment, as finding the answer and adapting it efficiently more closely matches the day to day job. The person that figures out how to copy and paste code for a REST call in that particular framework will still probably fail if they don't notice that they need to adapt it for the network request caching system and the ORM. But there is no reason to memorize…

I think we may be thinking about this differently.

I value reading the documentation of libraries that I'm using. I don't memorize it, but casually read over it to understand what's possible.

I do not do this for everything, but if it's a piece of technology that I value, then it's probably a good idea to read the docs so that I'm not faced with "I did not know that it could do that" situation.

The amount of times I've seen developers painfully code around something that was already supported in the library they're using is suprizing.

Re: If someone’s having to read your docs, it’s not “simple”

#84

Post by bob_roberts »

arduinomancer wrote: post #13

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.

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.

Re: If someone’s having to read your docs, it’s not “simple”

#85

Post by resonious »

csande17 wrote: post #28

Is it just me, or does this change in particular totally destroy the meaning of the sentence? Original: > Mailers are really just another way to render a view. "Edited": > Mailers are another way to render a view. The original sentence suggests that, while mailers may look different, they use the same underlying "render a view" mechanism (as some other part of Rails, presumably). The revised version makes it sound li…

To me, both sentences make it seem like I really want to render a view, and Mailers are one possible way.

Perhaps a more effective edit would just use controllers as an analogy from the beginning instead of focusing on views.

> Mailers are like controllers, but for email instead of HTTP.

Re: If someone’s having to read your docs, it’s not “simple”

#86

Post by vmception »

pistoriusp wrote: post #83
vmception wrote: post #72

Earlier quoted context omitted.

I interview people based on their ability to cheat on the assessment, as finding the answer and adapting it efficiently more closely matches the day to day job. The person that figures out how to copy and paste code for a REST call in that particular framework will still probably fail if they don't notice that they need to adapt it for the network request caching system and the ORM. But there is no reason to memorize…

I think we may be thinking about this differently. I value reading the documentation of libraries that I'm using. I don't memorize it, but casually read over it to understand what's possible. I do not do this for everything, but if it's a piece of technology that I value, then it's probably a good idea to read the docs so that I'm not faced with "I did not know that it could do that" situation. The amount of times I'…

I've had a handful of developers do this, mostly in frontend work with lifecycles because they didn't read

Re: If someone’s having to read your docs, it’s not “simple”

#87

Post by hardwaresofton »

antonvs wrote: post #70
hardwaresofton wrote: post #19

Earlier quoted context omitted.

If Stack Overflow ever changes their model/tries too hard to monetize, the resulting chaos will be bad initially, but will probably spur a shift to better documentation across the board. SO serves as unofficial documentation for a lot of projects and once that crutch is gone, it will force projects to either improve or (more likely) stop letting people file issues (because that's where all the stuff would go). Looks…

> If Stack Overflow ever changes their model/tries too hard to monetize On that subject, Stack Overflow was just acquired for $1.8 billion.

Yeah, I made this comment with that thought in mind! For all of SO's history I think it's safe to say they've been very generous (i.e. cognizant of what their platform offers/the potential risks of monetization in certain ways).

For what it's worth, I don't think Prosus will make a mistake in this way -- the fact that they've existed all this time without me (or most people, I think) ever hearing about them means that they are good at what they do. Regardless of what their main goals are, I assume that I'll think it's likely I continue to not hear about them.

Re: If someone’s having to read your docs, it’s not “simple”

#88

Post by atoav »

feoren wrote: post #51
atoav wrote: post #39

Earlier quoted context omitted.

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 i…

If you think writing down some good examples and explaining them takes "an hour", you have never written documentation. Writing good documentation takes forever !

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.

Re: If someone’s having to read your docs, it’s not “simple”

#89

Post by thiht »

bob_roberts wrote: post #84
arduinomancer wrote: post #13

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.

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.

Simple is the opposite of complex, not the opposite of hard. Saying something is simple has meaning, and it's not insulting.

Re: If someone’s having to read your docs, it’s not “simple”

#90

Post by dwaltrip »

antonvs wrote: post #73
Aeolun wrote: post #55

Earlier quoted context omitted.

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.

Meh. If someone just blindly believes some marketing blurb and ignore the blitheringly obvious challenges, isn't that at least a little on them?

Sure, perhaps. But people who make marketing content that contains bullshit or dishonesty shouldn’t get a free pass.
Post reply on HN