For the Love of God, Please Write Better Docs!

[poliklosio via Digitalmars-d]

On Friday, 5 August 2016 at 21:01:28 UTC, H.Loom wrote:
> 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:
>>> (...)
>> (...)
>> In my opinion open source community massively underestimates 
>> the importance of high-level examples, articles and tutorials. 
>> (...)
>
> 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.

I think we agree here. Most libraries are marginal, and missing 
proper announcement and documentation is the main reason they are 
marginal. Hence, this is true for most libraries.
Of course there are good ones, sadly not many D libraries are 
really well documented.

>> If you are a library author and you are reading this, let me 
>> quantify this for you.
>
> Thanks you ! you're so generous.

Why the sarcasm? I was just venting (at no-one in particular) 
after hitting the wall for a large chunk of my life.

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

I'm lost here. The "width of whitespace" was just an example of 
something you would NOT normally care about if you were a savvy 
user used who already knows how to navigate the docs.