On Monday, 6 June 2016 at 18:21:49 UTC, Johnjo Willoughby wrote:
On Monday, 6 June 2016 at 04:24:14 UTC, Jack Stouffer wrote:
On Monday, 6 June 2016 at 02:20:52 UTC, Walter Bright wrote:
* Documentation and tutorials are weak.
I never understood this, as I've always found D's docs to be
pretty average.
If you understand why they are "pretty average" you can imagine
what would make them better, that gives you two reference
points from which you can extrapolate back to a point at which
they are "fairly crap".
"fairly crap" on the graph is where new users come in because...
1. They are not yet fully invested in D, so do not have the
inherent bias of a convert.
2. They do not have long familiarity with the docs.
All that aside, it doesn't actually matter what you think or
whether you understand why it is a common complaint. It is
simply a fact that a lot of new users find the documentation to
be "fairly crap". So you can either choose to...
1. Flap your hands and bury your head in the sand.
2. Say it doesn't make sense, these people must be morons.
3. Fix the documentation to make it more accessible to new
users.
1 and 2 are the current solution from what I can see.
There documentation can also be classified as broken as broken
links were quite the annoyance for me. It's a minor
inconvenience, but one that has an additive effect every time I
encountered one using their site.
That being said. My major complaint is lack of coherent, relevant
or useful examples of what a function/type/template is actually
useful for. Most are just ripped out of unittests, provide no
context, and often use other library calls that aren't really
needed to solve a non-common, non explained problem.
