Andrei's list of barriers to D adoption

[poliklosio via Digitalmars-d]

On Monday, 6 June 2016 at 02:20:52 UTC, Walter Bright wrote:
> Andrei posted this on another thread. I felt it deserved its 
> own thread. It's very important.
> -----------------------------------------------------------------------------
> (...)
> * Documentation and tutorials are weak.

Regarding documentation, I'll just point out something that 
people seem not to understand here. I think the complaints about 
bad docs are not really about accuracy of what is displayed on 
the screen. I think accuracy is very good. They are more about 
usefulness and discoverability.
Its just the amount of cruft that a user has to go through to 
find out what exists and how he can apply it.

I'll pick on string documentation as an example. Other concepts 
will have different issues.

As a concrete example, how good is
https://docs.python.org/2/library/stdtypes.html#str.find
in comparison with
https://dlang.org/phobos/std_string.html#.indexOf
?

I think python version has several advantages:
- It is more conscise due to uniform handling of single char and 
string.
- It is more conscise due to not displaying a lot of pointless 
cruft that the user doesn't care about.
- It is more discoverable due to the name "find".
- It is more discoverable due to being a method of str type.

Problems with the D version are:
- There is heavy use UFCS, so things are split into different 
modules. String is an array, which means that UFCS must be used 
to extend it.
- The whole deal with dchar and unicode vocabulary all over the 
place, which adds to the amount of information. It would be much 
better to just assume correct Unicode handling and concentrate on 
how is a function different from other functions, as this is what 
user needs. Yes, details are good, but
- Strong typing in D has a lot of concepts that a newcomer has to 
learn before docs stop causing anxiety.
- The type constrains add visual noise.
- For the type constraints, it is hard to find what is the 
intention of their existence. It is typically not spelled out in 
English language.

Can something like this be made for the D version? I claim it 
can. We just have to drop the compulsion to document every detail 
and generate a simplified version of the docs.
I think such a simplified, python-like documentation could live 
as yet another version of docs that concentrates on usage rather 
than definition. It could contain links to the full version. :)

And, as a cherry on the cake, what is the first thing that user 
sees in the D version?
"Jump to: 2"
It is not readable at all. What is 2? Second what? What is the 
difference between the 2 things? I had to squint hard to find out 
(I wasn't lucky enough to read the first line of description 
first when I was finding out the difference. I started by looking 
at the function signatures). Those things should be described in 
english language somehow.

And regarding cheatsheets, as pointed out before, they don't work 
as a discoverability aid. You really need 2 or 3 sentences to 
tell what a fucntion does. A line of cryptic code that presents 
*one* data sample doesn't work.