Should this work?

[H. S. Teoh]

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


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


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


T

-- 
Computers shouldn't beep through the keyhole.