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.
