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