Lost a new commercial user this week :(

[Manu via Digitalmars-d]

On 15 December 2014 at 07:00, Kiith-Sa via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
> On Sunday, 14 December 2014 at 19:40:16 UTC, Walter Bright wrote:
>>
>> On 12/14/2014 12:37 AM, Manu via Digitalmars-d wrote:
>>>
>>> There were a few contributing factors, but by far the most significant
>>> factor was the extremely poor Windows environment support and Visual
>>> Studio debugging experience.
>>
>>
>> This is valuable information, while it's fresh in your mind can you please
>> submit a bugzilla issue for each point?
>>
>>
>>> They then made HUGE noises about the quality of documentation. The
>>> prevailing opinion was that the D docs, in the eyes of a
>>> not-a-D-expert, are basically unreadable to them. The formatting
>>> didn't help, there's a lot of noise and a lack of structure in the
>>> documentation's presentation that makes it hard to see the information
>>> through the layout and noise. As senior software engineers, they
>>> basically expected that they should be able to read and understand the
>>> docs, even if they don't really know the language, after all, "what is
>>> the point of documentation if not to teach the language..."
>>> I tend to agree, I find that I can learn most languages to a basic
>>> level by skimming the docs, but the D docs are an anomaly in this way;
>>> it seems you have to already know D to be able to understand it
>>> effectively. They didn't know javascript either, but skimming the
>>> node.js docs they got the job done in an hour or so, after having
>>> wasted *2 days* trying to force their way through the various
>>> frictions presented but their initial experience with D.
>>
>>
>> I understand what you're saying, but I find it hard to figure out just
>> what to do to change it. Any specific suggestions?
>
>
> One thing I ran into often when I was inexperienced with D:
>   the template constraints make some signatures extremely messy, and it
> takes a while to figure out when you have e.g. 3 template functions of the
> same name in
> std.algorithm, all with crypric signatures.
>
> Example:
>
> ptrdiff_t countUntil(alias pred = "a == b", R, Rs...)(R haystack, Rs
> needles) if (isForwardRange!R && Rs.length > 0 && isForwardRange!(Rs[0]) ==
> isInputRange!(Rs[0]) && is(typeof(startsWith!pred(haystack, needles[0]))) &&
> (Rs.length == 1 || is(typeof(countUntil!pred(haystack, needles[1..$])))));
> ptrdiff_t countUntil(alias pred = "a == b", R, N)(R haystack, N needle) if
> (isInputRange!R && is(typeof(binaryFun!pred(haystack.front, needle)) :
> bool));
>
> countUntil is trivial to use, but the docs make it seem complicated
> and it takes a while to read them.
> (This is not really a good example as with countUntil it's not *that*
>  bad, but I think it should be enough to show the problem)
>
> In this specific case, it would be useful if the constraint was somehow
> separated from the rest of the signature and less emphasized (CSS).
>
> Also, in this example, the documentation text itself immediately goes into
> detail (e.g. mentioning startsWith!) instead of starting with a simple
> explanation of the concept.
>
> I think this could be helped somewhat if the example
>
> This is one example of "too much noise".

This is an excellent example. That wall of text is totally unacceptable.
It was the string functions that had my colleagues head spinning.
He wanted to do some extremely basic string operations, and
to!int(myString)... these things were all very hard for him to
understand from the docs.