On Friday, 5 August 2016 at 19:52:19 UTC, poliklosio wrote:
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!
This is not true for widely used libraries. I can find everywhere
examples of how to use FreeType even if the bindings I use have 0
docs and 0 examples. Idem for libX11...Also i have to say that
with a well crafted library you understand what a function does
when it's well named, when the parameters are well named.
This is another story for marginal libraries, e.g when you're
part of the early adopters.
If you are a library author and you are reading this, let me
quantify this for you.
Thanks you ! you're so generous.
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%
congratz, you've taken care to reach exactly 100...
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.
For phobos i agree. D examples shipped with DMD are ridiculous. I
was thinking to propose an initiative which would be to renew
completly them with small usable and idiomatic programs.
Those who do get the general idea don't care much about the
exact width of whitespace and other similar concerns.
I don't understand your private thing here. Are you talking about
text justification in ddoc ? If it's a mono font no problem
here...
