Lost a new commercial user this week :(

Manu via Digitalmars-d digitalmars-d at puremagic.com
Wed Dec 17 00:06:25 PST 2014


On 15 December 2014 at 05:39, Walter Bright via Digitalmars-d
<digitalmars-d at puremagic.com> 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?

I'll probe for more feedback.
Sorry, I don't have work time allocated to this >_<


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

I don't really know either. I can recall my own experience that the
documentation was really confronting, but I'm used to it now, and I
don't refer it frequently enough to really care anymore.
I think any of us in this community will have trouble seeing the
problems with the presentation here.

One thing I know for sure, is when they are confronted with
constraints, especially on templates, they have absolutely no idea
what they're looking at... and even I find it hard to read them.
For my money, the constraints are less important information, and I
think it should be separated from the declaration in the docs.
Perhaps a better approach would be to convey that information in the
parameter descriptions; ie, "'A' must be a forwardRange".

I think there's also a lot of magic letters in function declarations,
especially in templates. I wonder if more meaningful names would help
in a lot of cases?

I think it would be a good idea to make the template args and the
runtime args look more visually distinct. D has a subtle template
syntax, and it would be good to have something that clarifies which
args are template or runtime args at a glance. It can look like quite
a confusing mess currently in many cases.


I'd suggest to look at high-quality commercial documentation, like
MSDN or wherever.
Here's one I'm familiar with:
http://msdn.microsoft.com/en-us/library/windows/desktop/hh309466(v=vs.85).aspx
My feeling is the MS docs are well organised, there's always the lest
amount of text on a page at any given time.
It starts with 'getting started':
http://msdn.microsoft.com/en-us/library/windows/desktop/hh769064(v=vs.85).aspx
Then there is 'how to's for many common tasks:
http://msdn.microsoft.com/en-us/library/windows/desktop/hh404569(v=vs.85).aspx
This is a reference for a class:
http://msdn.microsoft.com/en-us/library/windows/desktop/ff476379(v=vs.85).aspx
For comparison, our pages show reference for multiple classes, and you
can only tell that something is contained in a class with a subtle
indentation: (consider SList)
http://dlang.org/phobos/std_container.html

Each page only has one thing. It dynamically fetches bits of data as
you navigate, rather than reloading whole pages and assaulting you
with a wall of text.

Let's look at something else... Since none of us had ever written a
line of javascript, and we had to learn to write a node.js server in a
few hours, this came up: http://jquery.com/
They have interactive tutorials with video presentations and even a
theme song O_O: http://try.jquery.com/levels/1/sections/2
Their API reference is a bit lame compared to Microsoft, but the
function reference is pretty good:http://api.jquery.com/dequeue/
What's interesting about that link is they're doing something cool
that we already have; they have some example code, and they offer the
button to run it. We have that on the front page of dlang.com, but we
don't use it in the docs anywhere that I know of.

The node.js docs are disgraceful:
http://nodejs.org/api/child_process.html#child_process_event_disconnect
they're practically as bad as ours, but I find the styling much more
readable. Our docs are dominated by horizontal bars, weird colours,
random bold-ness, but no real distinctions in font size or style.
Their docs use text styling much more effectively than we do to my eye.

It's all subjective. My point is, the feeling I get from looking
around the big players docs, there is a clear difference in quality.
Past the installation process, and path to 'hello world', this is
probably the most important first impression the language will make.


More information about the Digitalmars-d mailing list