Frustratingly D

[Nicholas]

For about 2 months I've been sinking into D.  I really enjoy it and I want to
love it but I'm constantly annoyed by the presentation of information.
Several times I've built things that were in the standard library because the
website is poorly organized and doesn't contain sufficient examples.  The
online documentation has a bunch of cluttered links at the top, no hierarchy,
no dates, and it reads like a list of nutritional facts.  My only recourse is
to grep like mad through the source files and find the actual implementations
and unit tests.  It's bad enough that there are no modern IDEs so that it
already feels like it's 1994 again.


Here are some particular annoyances that need further
clarification/examples/comparisons to their siblings:
std.concurrency vs std.thread
std.date vs. std.datetime
std.regex vs. std.regexp
std.file vs. std.cstream and there's quite a bit of crossover with std.stream
std.xml: unfortunately one of the few modules that doesn't have a sibling.


And Andrei, you're a great programmer but your example-giving skills could be
strengthened.  From std.array to std.range to std.random, all your examples
are equivalent to this:
auto a = [ 1, 2, 3 ];
assert( ... );

auto a = obj.method( "guess what i'm returning" );


I like auto.  I use it sometimes.  But it's not always clear what's taking
place in the examples.  I believe you should exclude auto from all examples
except when explaining auto.


I see great potential in D and enjoy it.  I would like to see the
documentation improve and the standard library cleaned up.  I'm sure there are
a million reasons why it evolved into what it has so far but for a new user
those reasons are unimportant.  Put them in the "History of D".


No hard feelings.  Just some thoughts.