91–100 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.
Not sure about the percentage but plenty are from people that don't even bother to read what is available or buy a book! They just do stack overflow driven programming, question & paste.
Earlier quoted context omitted.
The word “just” is superfluous in the sentence, and to the author’s point can easily imply more simplicity in use, concepts, etc. than is warranted. Software documentation should be more like scientific article writing: passive, and having few or no modifiers like “trivial” or “just” or the like.
I actually see just as in a lot of cases as being as a painful indication of a gross trivialization of something. I regularly call out engineers when they say "just", in a lot of cases when I say - can you explain "just" they go and pull out their collection of familiarity and understanding. To which I usually ask - "How much of your understanding will the reader have?". When I ask them to remove the just, suddenly a…
I don't know, I really love when I see someone using painless, easy or trivial, my experience is usually that. I think they are nonnegotiable if you have a clue about what you are dealing with.
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.
Wow I could not agree with more with you. I think I'm finally improving my writing skills as well ! Also, I find it hilarious that you have an entire website dedicated to make your point. I would give a +2 for that ;)
id recommend focusing on documentation that goes through much more complex layers than fussing over this. And he's also misreading what simple means.
Agreed, but that's quite an axe to grind, with a domain and all...
As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.
Back in school I was considered a "leet hacker" who was good at computers. I "cracked" an encrypted Word document when someone forgot the password to it (I Googled how to do it). I built my own PC (I Googled how to do it). I downloaded MP3s before they were everywhere (I Googled how to do it). You get the idea...
Nowadays I get paid to do that stuff, but at home I fix my own car when I can, fix my plumbing when I can, fix and maintain my bicycles, do my own networking etc. How? You guessed it... I DuckDuckGo how to do it.
Another thing you should not do is name things “fast”. It will end up not being fast (esp when you find the next faster thing) or else someone will find security holes in it.
Another one is avoid referring to something as "new". Soon enough it will be old. For example, class names "MailSender" and then you add "NewMailSender". What do you call it when the "NewMailSender" is old?
NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.