Lost a new commercial user this week :(

[Kiith-Sa via Digitalmars-d]

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


Example of 'not teaching the language':

For the first few months using D, I had no idea what D 'range' (I 
knew Python) is and it made the docs harder to understand.

I think most or all mentions of terms important in D such as 
'range' should link to a *simple* explanation of what a 
range/whatever is (maybe in Ali Cehreli's book?).


Also... some docs are just plain lazy ("does something similar 
but not the same as this C function we couldn't even be arsed to 
link to"), missing examples (or missing *useful* examples, etc.)
- A lot of docs assume the reader knows some specific other 
language, not only C


I occasionally try to push minor doc fixes but currently I'm 
rather swamped, may do some work on that next summer.