Do not use adverbs in technical writing period
If someone’s having to read your docs, it’s not “simple”
11–20 of 146 posts
Re: If someone’s having to read your docs, it’s not “simple”
#1250% 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.
Re: If someone’s having to read your docs, it’s not “simple”
#13This 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.
Re: If someone’s having to read your docs, it’s not “simple”
#14Another 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.
You're right. In fact everyone should stop trying to paint any of their products in a positive light.
Re: If someone’s having to read your docs, it’s not “simple”
#15Agreed, but that's quite an axe to grind, with a domain and all...
Re: If someone’s having to read your docs, it’s not “simple”
#16Another 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.
Also, it's always relative.
Re: If someone’s having to read your docs, it’s not “simple”
#1750% 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.
Something that bugs the hell out of me is any file-location or file-name configuration-by-convention thing where every example doesn't clearly state WTF file it's supposed to go in and link to a full example to provide any necessary context. "Gee, I guess I'll scan the whole page... nope, not anywhere on this page, now I get to click around your docs menu trying to figure out where this goes. Thanks." Half the time I end up poking around on GitHub trying to find a project that uses it, so I can figure out where it goes.
Re: If someone’s having to read your docs, it’s not “simple”
#18Another word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.
Years ago, I read Michael Crichton's autobiography "Travels". In that book there is one particular part that, for whatever reason, cemented itself in my memory. He recounts how his father shared a lesson with him regarding the word "Obviously", and it was something along the lines of "If you say it's obvious, but it isn't, then you will offend someone. If it is obvious, then it's superfluous. The word 'obvious' never…
That's a good point. I've also tried to eliminate the word "obviously" from my vocabulary. The one exception, as you pointed out, is reassuring someone in some positive manner.
Re: If someone’s having to read your docs, it’s not “simple”
#1950% 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.
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 like GitHub is already getting ahead of this with the "Discussions" feature.
Re: If someone’s having to read your docs, it’s not “simple”
#20Another word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.
Well it conveys the information: no further documentation on this available anywhere