Lost a new commercial user this week :(

[Tobias Pankrath via Digitalmars-d]

> We didn't 'learn' javascript, or python, or html, or whatever 
> else you
> pick up on the job.
> The investment in learning 'programming' is decades behind us, 
> and I
> think it's a reasonable expectation that a language present 
> itself in
> such a way that it's intuitive and easy to get some basic things
> going.
> Leveraging small example snippets from the docs, etc. D is very 
> easy
> for a C/C++ programmer, but the docs don't make it appear that 
> way,
> and they give the wrong impression.
> The overpowering presence of templates in the docs give a first
> impression that reminds people of everything that's wrong with 
> C++,
> which I suspect most C++ programmers looking into D are actively
> trying to escape!
>
> There simply can't be friction on step 1! There can be friction 
> on
> step 4 or 5 when you've already made some minor achievements, 
> and have
> a good few hours invested.
> Any friction on step 1 or 2 will lead to an almost immediate 
> rejection.

I second this. I remember very well that the docs really annoyed 
me
when I was starting with D. Sadly I can't see the issues I had
any more, because I'm used to it now, so it's kind of hard to
improve in a meaningful way.

But two things come to mind. The first is that the language 
documentation actually is a very dense language specification. If 
you look at the rust documentation you'll find a ‘Guide’ and a 
‘Reference’. We need such a tutorial as well. Just linking to 
some books is not enough.

Second thing is template arguments and constraints. For example 
std.container.Array has a specialization for bool. That looks 
like this in the docs:

std.container.Array(T) if(is(Unqual!T == bool)) vs.
std.container.Array(T) if(!is(Unqual!T == bool)).

That's super unhelpful for newcomers. The difference is hard to 
spot, newcomer don't know what a qualified or unqualified type is 
and they won't recognize the is-expression.

I think the documentation should call those to overloads Array!T 
and Array!bool.