Good q! To me there should be a good ratio of "accuracy scent" to "usefulness scent".<p>Some documentation is clearly written for subjective accuracy & coverage. The author really wants to nail down the full set of conditions or rules that applies to the given term, section, keyword, etc. Each sentence builds on the last. There will be no skimming here--you must be a sequence-consumer and maybe even some kind of logic-critic to really enjoy this.<p>That's nice unless you aren't wired for that kind of reading, or you've got other things to do, and you need a common answer or solution fast, and there's no FAQ or it's not in the FAQ. Someone told you to read the docs, and you start to realize that the docs are more of a schema than a how-to. Well, sometimes that really sucks.<p>But also sometimes there's not enough accurate coverage, and the docs simply say e.g. "this function draws a line" and even offer some examples. But none of the examples cover all the stuff that you can do with the function and there are clearly a number of additionally usable keywords or options up there, and if you look in the language source there are a bunch of single-letter vars all over the place with no comments.<p>So there's this gap between "here's how this part works & you're on your way" (casual) and "here's REALLY how it works" (orthodox) that is worth giving reasonably both-sided attention IMO if you want to strike a good balance for readers.<p>Some other factors: Is the documentation kept up to date, does it cover OS-integration factors (e.g. where is the config kept and how does it work), how does it read on mobile, how well does the web menu work, is there a URL segment per topic, is there a link from docs back to language home page (not just a self-contained doc blob), etc.<p>A bit of a tangent, but I do think some basic web sense can help if the docs will be published on the web. I recently worked with the maintainer of a wiki help manual for a programming language on this. It seems they had spent a LOT of time deciding which camel case words to use for their wiki, something like a decade ago.<p>And now the problem is, somebody has since taken the official docs to a different domain name, improved the SEO by demoting camel case in favor of fully descriptive page titles, let the docs go out of date, and now there are these obsolete docs with much better SEO that outrank the official up-to-date docs. And this third party can't be reached, so the creative solution is to do tons of SEO-style work on the current docs.<p>Which of course, SEO is the absolute favorite topic of every programmer, especially when someone else is showing them how much their SEO needs to improve :-) /s<p>Anyway! Good luck with your blog post or docs project.