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.
