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
