Should this work?

[Andrei Alexandrescu]

On 1/10/14 6:14 PM, Manu wrote:
> Maybe I can convey some tough love too.

Awes.

> The docs are terrible;

Agreed, no need to even argue!

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

My perception (and excuse me if I was wrong) was that you came to the 
discussion already indisposed: you had no knowledge of the general 
phobos approach and little interest in acquiring it. Instead, you had to 
do some simple string manipulation and expected it to be done the C way, 
and if not the hell with'em all. That sets up things in a way that makes 
it difficult to negotiate.

So the FM is bad. At a point though it does need to be read.

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

One aspect of that is you know you can contribute to the FM :o).

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

Mos def. Particularly the part about the FM being bad is quite clear.

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

But intuition is a subjective matter. What's intuitive for one is not 
for the other. You seem to find strrchr the pinnacle of being intuitive, 
and I think it's a piece of of dung.

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

Great. Let's do that for std.simd.

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

In fact I know independently from several friends that iOS has really 
good FMs for their APIs compared to Android.


Andrei