Blocking points for further D adoption

[David via Digitalmars-d]

As someone who recently tried D and dropped it to learn Python I 
can tell you, tooling was not an issue for me. I worked on a 
windows computer (which it seems a lot of this community are 
linux users based on the examples I see in the 
documentation...very *nix type examples) I will say I had dmd + 
codeblocks up and running and a hello world programming printing 
to the console in < 20 minutes.

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

But I should probably show some examples, because this post is 
meant to be productive not just critical.

Looking at the std.algorithm module page we get a description of 
functions that...well aren't really descriptions. For instance:

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.

The other beef I see, is that examples for functions seem like 
they are just ripped from random unittests and frequently 
reference other standard library calls without context of what 
they are doing.

For example readText:

https://dlang.org/library/std/file/read_text.html

It provides an example of this:

import std.string;
write("someUniqueFilename", "abc\n");
scope(exit)
{
     assert(exists("someUniqueFilename"));
     remove("someUniqueFilename");
}

enforce(chomp(readText("someUniqueFilename")) == "abc");

So reading it, it looks like we crate a file with "abc" in it, 
then do some scope(exit) thingy, then assert the file exists, 
then remove it? Odd...

Then we move down and it looks like "after" we delete it we read 
the file using "readText" and make sure it's contents are equal 
to what we wrote to the file? So first thing I had to do is look 
up what the hell scope(exit) was doing and found that it gets 
called when the scope gets killed not inline where it was. Ok 
fine. That sounds useful. So by the time we get to the readText 
line we still have a file. But what the hell is chomp? Do I need 
chomp to use readText? Turns out...no...I read a file literally 
by doing auto text = readText(fileName). So yeah...

To understand this example I had to a lot more work than I should 
of had to just understand how to use readText correctly, and it 
turns out I didn't need to do 90% of the code for my purposes, 
which means the rest is really more of just a distraction. Sure, 
I learned what scope(exit) does and what chomp did, but I didn't 
need them.