Blocking points for further D adoption

[ag0aep6g via Digitalmars-d]

On 06/05/2016 02:58 PM, David wrote:
> D's major issue is it doesn't have much of a presence on sites like
> stackoverflow (or at least they don't appear to show up well in my
> google searches) and the documentation google does give me links to are
> poorly done. Two main issues I saw? Broken links and poor examples. Also
> occasionally I get pages that look like a different a style from google
> searches than the main documentation pages, which makes me feel one is
> outdated. I ended up actually just going to dlang.org itself to be sure...

The different style pages are most probably dlang.org/phobos/ pages and 
dlang.org/library/ pages. They are built from the same source, so they 
should contain the same information. Neither of them should be outdated.

We're actively working on bringing the new style (/library/) up to 
speed. If you've hit broken links recently (in the last few days), it 
would help us if you could point them out.

[...]
> clamp    clamp(1, 3, 6) returns 3. clamp(4, 3, 6) returns 4.
>
> Yeah...that does not explain anything. Definition writing 101 tells you
> to never use the word you are trying to define in the sentence defining
> it. In fact, most of the descriptions for the functions in std.algorithm
> should probably come with better descriptions. D doesn't offer a lot of
> return on investment for learning it, so you could at least make it easy
> to learn...
>
> isPermutation    isPermutation([1, 2], [2, 1]) returns true.
>
> ^^^ How is that helpful? BTW, I'm getting this from this page:
>
> https://dlang.org/library/std/algorithm/comparison.html
>
> Now, if I click on each function I get a little bit better of an
> explanation (in some cases), but why have a useless description? It
> serves nothing and just distracts. You might as well as not have a
> description column on std.algorithm, and just provide links.

Interesting. We've been thinking about this exact thing lately [1]. So 
from your fresh experience, the "Cheat Sheet" is not very helpful.

If you scroll down on that documentation page you get to another table 
under the heading "Functions". It looks very similar to the cheat sheet, 
but the descriptions are different. (Having two almost identical tables 
like that is the problem we're trying to fix.) Would you consider the 
description in the "Functions" table more helpful than the ones in the 
"Cheat Sheet"?


[1] http://forum.dlang.org/post/niv2hc$2l7k$1@digitalmars.com