On Wed, 17 Dec 2014 10:49:19 +0000
Tobias Pankrath via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

> On Wednesday, 17 December 2014 at 10:33:34 UTC, ketmar via Digitalmars-d wrote:
> > On Wed, 17 Dec 2014 09:48:26 +0000
> > Tobias Pankrath via Digitalmars-d <digitalmars-d@puremagic.com>
> > wrote:
> >
> >> std.container.Array(T) if(is(Unqual!T == bool)) vs.
> >> std.container.Array(T) if(!is(Unqual!T == bool)).
> >> 
> >> That's super unhelpful for newcomers.
> > that's why newcomers should NOT try to learn the language using reference documentation for standard library.
> >
> > when i started to learn D, i found and read Andrei's book,
> > Ali's book
> > and Philippe's "template tutorial". and i never complained that
> > phobos
> > reference documentation is "hostile to beginners" -- 'cause
> > it's NOT
> > for beginners. you are expected to learn the language before
> > reading
> > reference dox.
> >
> > yet i agree that formatting can be better. but as i tend to
> > produce
> > completely unreadable mess when i trying to fix any formatting,
> > i
> > didn't do anything in that direction.
> 
> I don't think we should require newcomers to understand the is-expression (Even now I have to look it up now and then) and notion of a qualified type and to look of what that Unqual(T) template actually is, just to understand the documentation of an simple container, something that many newcomers will use to write small programs while learning the language.

that is exactly why i'm telling that reference documentation is not for beginners at all. it has some sample code, but you are expected to understant the language first.

what we really need is more "intermediate level" books that will teach people how to "think functionally" and use various Phobos modules. something like Adam's cookbook, maybe, but dedicated to Phobos, and promoting "everything is a range" style of thinking. ;-)

reference documentation can never be such book, 'cause it will be unusable as *reference* in that case.

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

On 2014-12-17, 2:41 AM, Dicebot wrote:
> On Wednesday, 17 December 2014 at 10:33:34 UTC, ketmar via Digitalmars-d
> wrote:
>> when i started to learn D, i found and read Andrei's book, Ali's book
>> and Philippe's "template tutorial". and i never complained that phobos
>> reference documentation is "hostile to beginners" -- 'cause it's NOT
>> for beginners. you are expected to learn the language before reading
>> reference dox
>
> I wonder how much of a loss it would be to Andrei to publish TDPL for
> free on dlang.org and link it from a front page as newcomer starting
> point. I don't know if there are still many people who buy it though.

I bought my copy just under 1 year ago (2 copies really, print + kindle).

On Wed, 17 Dec 2014 15:01:30 +0000
Wyatt via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

> > 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_.
did you seen at least one template in winapi? and at least one constrained template? it's easy to remove constraints from phobos dox. guess what people will say then? "dox is awful, there are no clearly seend constraints there!"

> 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!
either i forgot something, or perl doesn't have templates too.

> Bull.  D isn't magic and expecting that people need to set aside a chunk of time to "learn" it is really silly.
i hope such people will never adopt D.

> But it's not as silly as the idea that you don't learn the language by diving in.
using the tools you never used before, without training, to solve production tasks. this is what seems to be silly for me.

>   You know, by using it (and the standard library) to solve a
> problem?  This is simply how people pick up new programming
> languages.
so i'm not a human then.

> 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.
if people want to use reference documentation to learn the language, i myself prefer this people to use anything except D. and i bet that php is what they want.

On Wednesday, 17 December 2014 at 15:15:41 UTC, ketmar via Digitalmars-d wrote:
> On Wed, 17 Dec 2014 15:01:30 +0000
> Wyatt via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
>
>> > 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_.
> did you seen at least one template in winapi? and at least one
> constrained template? it's easy to remove constraints from phobos dox.
> guess what people will say then? "dox is awful, there are no clearly
> seend constraints there!"
>
>> 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!
> either i forgot something, or perl doesn't have templates too.
>
>> Bull.  D isn't magic and expecting that people need to set aside a chunk of time to "learn" it is really silly.
> i hope such people will never adopt D.
>
>> But it's not as silly as the idea that you don't learn the language by diving in.
> using the tools you never used before, without training, to solve
> production tasks. this is what seems to be silly for me.
>
>>   You know, by using it (and the standard library) to solve a problem?  This is simply how people pick up new programming languages.
> so i'm not a human then.
>
>> 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.
> if people want to use reference documentation to learn the language, i
> myself prefer this people to use anything except D. and i bet that php
> is what they want.

Btw, a guy I know could go into a D program I had written and change things as needed by simply looking at the code and the library reference. He had no previous knowledge of D. It is possible to do that in D as well. In order to use the full power of the language, you have to invest time, however. Same goes for any of the more complex languages.

On Wednesday, 17 December 2014 at 15:01:32 UTC, Wyatt wrote:
> 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.

Yep, MSDN is pretty good. I often end up there when other sources fail. They are also quite good at documenting what version you need to use a feature.

> _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!

I'd like to see the phobos documentation in a XML format. That would make it a lot easier to parse, analyse and generate improved extended documentation.

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

Commented code in tutorials and a collection of short idiomatic examples + good reference documentation with fast-easy-and-precise lookup goes a long way.

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

Yep, that is how I felt about Haskell when using the interpreter many years ago, but this:

https://tryhaskell.org/

is enough to get me beyond the initial "headache" that the weirder aspects of Haskell may cause (such as the function signatures).

Such interactive walk-throughs of the basics are really useful if you want to ease the learning curve in a fun way.

On Wednesday, 17 December 2014 at 09:05:58 UTC, Manu via Digitalmars-d wrote:
> On 16 December 2014 at 00:04, Kagamin via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
>> On Sunday, 14 December 2014 at 08:37:36 UTC, Manu via Digitalmars-d wrote:
>>>
>>> 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.
>>
>>
>> Comparing node.js to D? You probably speak about vibe, not D?
>
> The majority of hours spent were not really related to vibe.d so much
> as trying to wrangle the tooling, debugging crashes, and understand
> the docs to get some very basic things done.
> These are 'D' experience if you ask me.

very well said. it's not about just the environment, the language or phobos. it is about the experience that we provide to a new comer to D.

i remember walter said "build it and they will come is a lie." well, how about it "give a better experience and they will come?"

>
>
>>> One of the take-away quotes I think, was "D seems to be a language for
>>> people who actively want to go and look for it, and take the time to
>>> learn it. That's never going to be a commercial success."
>>
>>
>> O_O Huh? Your team really didn't learn C++?
>
> We didn't 'learn' javascript, or python, or html, or whatever else you
> pick up on the job.
> The investment in learning 'programming' is decades behind us, and I
> think it's a reasonable expectation that a language present itself in
> such a way that it's intuitive and easy to get some basic things
> going.
> Leveraging small example snippets from the docs, etc. D is very easy
> for a C/C++ programmer, but the docs don't make it appear that way,
> and they give the wrong impression.
> The overpowering presence of templates in the docs give a first
> impression that reminds people of everything that's wrong with C++,
> which I suspect most C++ programmers looking into D are actively
> trying to escape!
>
> There simply can't be friction on step 1! There can be friction on
> step 4 or 5 when you've already made some minor achievements, and have
> a good few hours invested.
> Any friction on step 1 or 2 will lead to an almost immediate rejection.

i am a python, ruby and groovy developer. D was very easy also for a programmer like me. every time i come back, i find comfort at D. honestly, D is python on stereoids for me. till i look at the docs and see all those things that doesn't mean anything at first sight. then i spend some time to understand the signatures, the bodies.

maybe, generated docs are not a good idea and hand-written, more explanatory docs are better for d?

On Wed, 17 Dec 2014 16:08:43 +0000
Chris via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

> Btw, a guy I know could go into a D program I had written and change things as needed by simply looking at the code and the library reference. He had no previous knowledge of D. It is possible to do that in D as well. In order to use the full power of the language, you have to invest time, however. Same goes for any of the more complex languages.
yes, it is possible to make small hacks here and there. but in no way it is possible to throw people writing production code without proper training in new language. that code will barely work (if it is at all) and will be unmaintainable mess.

On Wednesday, 17 December 2014 at 15:15:41 UTC, ketmar via Digitalmars-d wrote:
> On Wed, 17 Dec 2014 15:01:30 +0000 Wyatt via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
>
>> And yet they have much better organisation and they're much
>> _less noisy_.
> did you seen at least one template in winapi? and at least one
> constrained template?

Irrelevant to my point.

> it's easy to remove constraints from phobos dox.  guess what
> people will say then? "dox is awful, there are no clearly seend
> constraints there!"
>
Wooooah, hold up there, pal!  At no point has ANYONE advocated removing the constraints from the documentation entirely.  Could you please stop pretending that every suggestion for change involves a shift of extremes?

>> 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!
> either i forgot something, or perl doesn't have templates too.
>
Again, this is irrelevant to the topic, which is "Phobos documentation is accurate but often somewhat unreadable, and that's a bad thing".  I made this point to reiterate that even a language reviled for being "write once; read never" often has clearer documentation.

>> Bull.  D isn't magic and expecting that people need to set
>> aside a chunk of time to "learn" it is really silly.
> i hope such people will never adopt D.
>
It's too late; we're already here.  With a niche language like this (I hate to admit it, but that's how it is) that's probably most of the people that pick it up.

>> But it's not as silly as the idea that you don't learn the
>> language by diving in.
> using the tools you never used before, without training, to
> solve production tasks. this is what seems to be silly for me.
>
And over here, in reality, not every situation is optimal and we often find ourselves doing just-in-time learning.  Learn how to learn by doing and accept that you're going to exercise that skill.  A lot.  If you need a bunch of training up front just to get things done, you're probably in the wrong field.

>>   You know, by using it (and the standard library) to solve a
>>   problem?  This is simply how people pick up new programming
>>   languages.
> so i'm not a human then.
>
Well duh, you're a unicorn.  Didn't you get the memo? ;)

> if people want to use reference documentation to learn the
> language, i myself prefer this people to use anything except D.
> and i bet that php is what they want.

And I'm sincerely glad this sentiment isn't prevalent in the community.  Leave that attitude with C++.

-Wyatt

The worst part of the docs is the mass of linked text at the top. When are we going to switch to the new layout? It's much better than the current layout.