Should this work?

[Manu]

On 11 January 2014 03:32, Andrei Alexandrescu <SeeWebsiteForEmail at erdani.org
> wrote:

> On 1/10/14 9:01 AM, Kira Backes wrote:
>
>> On Friday, 10 January 2014 at 16:28:58 UTC, Andrei Alexandrescu wrote:
>>
>>> On 1/10/14 6:02 AM, Manu wrote:
>>>
>>>> What's the go with popFront()... it returns nothing?
>>>> I almost always want to pop and return the front element.
>>>>
>>>
>>> http://dlang.org/phobos/std_range.html#.dropOne
>>>
>>> What do you want us to do, RTFM to you?
>>>
>>
>>
>> I think he wants to return the popped element and this function does not
>> do it. So it may actually be a missing convenience function.
>>
>
> Oh, I misunderstood. Anyhow, just wanted to convey some tough love to him
> :o).


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.
You personally have an obvious bias; naturally this stuff seems reasonable
and intuitive to you, you wrote most of it.

This thread is basically an account of my experience at face value diving
into something new(-ish). I personally think it's valuable in some way;
these are accounts of specific hurdles that may trip others, but you're
welcome to tell me to RTFM.
Unlike someone who's looking at D for the first time, I know a lot about
the community, development process, and also many other parts of the
language. But I can hopefully still produce a reasonably objective
first-impression towards things I haven't really touched yet. I can
certainly highlight the rough edges.

I think we've highlighted here that the documentation, errors, location of
functions, and perhaps some of the names needs greater consideration, that
is all. I'm not arguing with the concepts, just that it's surprisingly
simple to fall into traps if you don't already know what you're doing, and
then the errors often don't help you identify and fix the problems so much.

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?
Claims of RTFM are often a failure of intuitive design. And sure, that's a
subjective quantity, but you can't approach a design WRT intuitive-ness
without feedback from a whole bunch of different first impressions.

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.

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.
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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20140111/a2b760a1/attachment-0001.html>