71–80 of 146 posts
50% of the questions on Stack Overflow are probably because the documentation was not great in the first place. I am surprised how much configuration/installation time I spend on there.
As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.
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 all that syntax and regurgitate it in the most computationally efficient Big O
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.
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.
I've had a blog post rolling around in the back of my head for years regarding how "obviously" is the absolute worst word to use in any kind of technical context. And then go through some of the most egregious things labeled as obvious in various peer reviewed research or blog posts.
Me: new (to me) high school, 1978. In the headmaster’s western civ class. In the first test (three questions, answer one, use as many blue books as you need) I wrote, “Obviously...”. When the results were handed back I looked at my book. Where I had written, “obviously” he had crossed out that word and a lot of subsequent text. He wrote, “since it was obvious I didn’t bother to read it.” Forty odd years later I have…
And omitting the word "obvious" wouldn't make the statement any less obvious. Wouldn't his explanation demand he cross out any basic true statements, no matter how you worded them?
There are good arguments for avoiding the word "obviously" in many circumstances... but I don't buy that argument.
Do not use adverbs in technical writing period
50% of the questions on Stack Overflow are probably because the documentation was not great in the first place. I am surprised how much configuration/installation time I spend on there.
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.
And he's also misreading what simple means.
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.
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.
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…
It needs clear wording, perhaps like "this is a wrapper around" or "this is an alternative to" or "this is one of the" followed by more detail.