For the Love of God, Please Write Better Docs!

[H.Loom via Digitalmars-d]

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...