Lost a new commercial user this week :(

[Wyatt via Digitalmars-d]

On Wednesday, 17 December 2014 at 10:16:22 UTC, ketmar via 
Digitalmars-d wrote:
> On Wed, 17 Dec 2014 18:06:25 +1000
> Manu via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
>
>> I'd suggest to look at high-quality commercial documentation,
>> like MSDN or wherever.
> please, no! the fact that you are used to it doesn't mean that
> msdn is a quality dox.
>
Frankly, I think you're letting your prejudices against the 
source of the documentation cloud your judgement of the quality.  
Much as I hate to admit it, their _reference_ documentation is 
much more readable at the baseline.

> besides, msdn references are exactly what phobos documentation
> is: description of functions. will msdn reference dox help you
> to learn msvc? yet you citing it as "high-quality" and blaming
> phobos dox for doing (or, rather, not doing) the same.
>
And yet they have much better organisation and they're much _less 
noisy_.  This is what we mean when we talk about "quality" in 
documentation.  Hell, a lot of CPAN docs are easier to follow 
than the Phobos stuff, and that's _Perl_ for crissakes!

>> 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...
> did they ever tried to learn the language? seems that you just
> throwed phobos dox at them and expecting them to use that dox to
> learn D.  D is not C. D is not C++. one must learn it before
> using it.  and phobos documentation is not for learning the
> language, it's reference for phobos.
>
Bull.  D isn't magic and expecting that people need to set aside 
a chunk of time to "learn" it is really silly.  But it's not as 
silly as the idea that you don't learn the language by diving in. 
  You know, by using it (and the standard library) to solve a 
problem?  This is simply how people pick up new programming 
languages.

> i bet the story was like this: "guys, look at this cool
> language, it's almost like C++, and has some great features!
> let's use it!" "ah, almost like C++? so we don't have to learn?
> great, let's do it!  but...  hey... what do all that gibberish
> in documentation mean? i've never seen that is C++... screw it,
> this wannabe C++ language is awful!"

It's more akin to the Haskell reaction: "This seems neat, but 
it's asking way too much of me and I don't have time for it."  We 
know this isn't how the language _actually_ is; that it's really 
quite forgiving and friendly if you know any other curly-braces 
language, but you'd never know by looking at the docs.

-Wyatt