For the Love of God, Please Write Better Docs!

[poliklosio via Digitalmars-d]

On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
> (...)

I cannot agree more with that.

In my opinion open source community massively underestimates the 
importance of high-level examples, articles and tutorials.
To most library authors (judging from projects I've seen) source 
code and reference docs is 90% of usability and everything else 
is 10%. This is completely wrong and upside-down!

If you are a library author and you are reading this, let me 
quantify this for you.

Influence of parts of documentation on usability:
- Good tutorials and high-level examples for typical actual 
use-cases: 60%
- Good README file with very clear instructions for installation 
and any other setup, e.g. interoperation with typical set of 
other libs: 25%
- An article in prose explaining motivation for the library: 10%
- Examples in online reference documentation: 3%
- All the other elements reference documentation, source code 
readability: 2%

This has no scientific basis, but I felt compelled to use numbers 
because words cannot illustrate the massive extent of the problem.

Again, if you are a library author and you think this rant is 
silly then yes, your documentation is that bad.

This also explains part of complaints on Phobos documentation - 
people don't get the general idea of how to make things work 
together. Those who do get the general idea don't care much about 
the exact width of whitespace and other similar concerns.