Should this work?

[Manu]

On 11 January 2014 14:20, H. S. Teoh <hsteoh at quickfur.ath.cx> wrote:

> On Sat, Jan 11, 2014 at 12:14:55PM +1000, Manu wrote:
> [...]
> > Maybe I can convey some tough love too.
> > The docs are terrible; very unhelpful (often just one line that
> > basically repeats the function name), which is particularly
> > problematic since phobos is far from intuitive (to me at least), and
> > most people here probably severely underestimate the magnitude of the
> > problem, since they've all closely watched the development of phobos
> > step-by-step, participated in discussions related to it's design
> > merits, and generally grown alongside the body of code.
>
> I'm sure we're all well aware of the documentation problem. Pull
> requests are always welcome. ;-)
>
>
> [...]
> > I've seen a lot of promotion recently positioning this stuff as a
> > superior use case for D. And maybe it's true, but that's not
> > apparently at face value.
> >
> > If this is to be one of D's 'killer-features', and a major selling
> > point for D, then it needs to be polished to perfection. Currently, it
> > is not.  Telling people to RTFM isn't helpful, if it were intuitive
> > and they didn't fall into minor traps in the first place, then it
> > would be a non-issue.  Which is a better place to be in?
>
> The problem with this is that "intuitive" means different things to
> different people.
>
> The other issue is that what we need at this point is not just to polish
> up the library docs (which, as we all know, needs lots of love). We also
> need *tutorials* targeted toward new learners, which right now are even
> more scant than Phobos docs, sad to say. Things that introduce key
> concepts that, if you don't grok it, you won't be able to really use the
> language effectively. Just as if you don't understand what a pointer is,
> your C code is going to have problems of a fundamental sort, certain
> things in D require that you understand key concepts, like ranges. Right
> now, though, these things are buried deep under obscure layers of
> incomprehensible (to a newbie) docs, so they may never find it.  The doc
> header in every module's docs should have an explanation of such key
> features, at the very least. Plus, we also need "bird's-eye view"
> tutorials that explain, in a very general way, how things are laid out
> and where to look for things, what you must know to understand the
> layout, etc.. Phobos does have an overview page, but it's so out of date
> and no longer accurate that I'd argue it's actually detrimental, not
> just unhelpful.
>
>
> [...]
> > Here's an idea; next time a phobos module is released, specifically
> > request that people give it a spin without reading the docs (using
> > only auto-complete popups and intellisense), ask them to keep a
> > journal of significant moments in their experience; ie, moments when
> > they had to resort to the docs, when they tried something that didn't
> > work how that imagined, when they were confused by conflicting
> > function names and not sure which to choose. Gather a bunch of these
> > reports, and there's a very good chance that the author may be able to
> > improve the intuitive design of their module significantly.
>
> While this might be a helpful exercise to locate problematic parts of
> the API, IMO "intuitiveness" is overblown. It is no substitute for
> actually reading the docs and learning how to use something effectively.
>

I think you underestimate the importance of someone new to something (and
probably with zero, or less, vested interest) being able to just getting in
and do something useful with as little friction as possible.
The positive impression left by that experience is huge. With this as a
starting point, users will often learn the finer details through
observation, experience, and osmosis.

Many(/most?) programmers don't love programming; it's a job. They have a
task to complete, and the sooner they get it done, and it works properly (D
promotes correctness, this is the correct approach), the sooner they can go
home and get on with shagging the mrs, or watching tv, or whatever they
prefer to be doing.
Many(/most?) programmers I've worked with have never read a programming
book (other than maybe some material at school), they simply don't care
enough.
Naturally this forum is full of very committed enthusiasts, and that
fosters an unrealistic perspective of what programming is to most
programmers, and the investment people are realistically expected to make
in learning a new thing.

I just want to reiterate (I've made this point before) that most of my
criticisms/complaints here are positioned from the angle that I always try
to approach D like 'the average joe programmer'. I've been a project lead
on large teams, and before I can realistically imagine adopting D
full-scale in the commercial environment, I need to be convinced that these
kinds of people are properly satisfied, certainly, they make up the
majority of professional programmers.

Driving a car is pretty intuitive -- nobody needs anyone to teach them
> that you just turn the key in the ignition, step on the gas, and off you
> go -- but if this is *all* they know, you'd hardly call their driving
> "effective", nor will you feel comfortable handing the keys over to
> them.
>

I'm not convinced this is a good analogy.

> There's a reason Apple are so successful. It's because rather than
> > telling their users to RTFM and harden up, they use extremely careful
> > design and lots of feedback to factor out the issues people are likely
> > to encounter in the first place.
> [...]
>
> To be quite honest, I find Apple's interfaces an annoyance to use. But I
> know I'm in the minority in this issue. :-)
>

Me too, but until Google(/Samsung?) outright lifted their ideas and
lessons, they were the dominant force by far, and for good reason.
Again, you (and I) are an enthusiast, and among the severe minority...
although the analogy doesn't work so well anymore, because Android lifted
the good bits from iOS, and Apple hasn't done the same in return, so iOS
has kinda fallen behind, even with mainstream users. (In fact, I wonder if
that's even a valid demonstration of the principle I'm trying to
illustrate?)

> That is the world today, that is where the bar is. D will be wildly
> > successful on the day that programmers that have never seen it before
> > can come along, effortlessly write whatever code they're trying to
> > write, offered useful help by the compiler along the way, walk away
> > feeling really smart and happy with their experience.
> >
> > Likening the experience to when I was learning C 20 years ago (earlier
> > in this thread) is completely worthless, there was no internet, no
> > competition, and the bar was so much lower then.
>
> While I agree in principle, I still think that intuitiveness is
> overblown. Computation is complex -- inherently complex -- and you can't
> expect to just dawdle in and wing it and get good results without ever
> spending any effort to learn anything. That's no excuse for things that
> *should* be easy to do being unnecessarily difficult, of course, but you
> can't expect good results for no effort. The universe just doesn't work
> that way.
>

Some of the things I'm talking about are trivial things like function
names, and where the functions should be found, whether there are 2
functions named similarly enough to cause confusion over which one is which.
I think these sorts of 'trivial' API details are far more significant than
has been recognised.
The fact that my question about popFront spawned 10's of emails, and
conversation about things like dropFront, moveFront, and there was
legitimate controversy over what things did, and every person that said
what I wanted already existed was wrong... and there are powerful
authorities in this thread.

There simply can't be a thread with hundreds of posts about something
that's dead obvious.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20140111/586352c0/attachment-0001.html>