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.
