On Saturday, 26 August 2017 at 22:26:00 UTC, Ecstatic Coder wrote:
I've no problem with that, but would it be possible to consider
adding also a link to this tutorial in the same paragraph ?
https://www.tutorialspoint.com/d_programming/
It's not because TutorialsPoint pay me, but because it may be
one of the best D tutorials out there for both beginner D
programmers.
And honestly, at the moment it's not really that easy to reach
this tutorial from the dlang website.
First you have to push on "Tutorials", then in the middle of
the page you see a boring flat grey icon with this text beside :
"D programming
Unknown
January 1, 2015
A nice introductory tutorial to D programming. Available
on-line and in the PDF format.
Website"
The text is fine, but unfortunately the impersonal icon and
text ("D programming") aren't that inviting...
If you don't want to put the link on the "Further reading
page", maybe would you consider putting this nice tutorial for
beginners just under the four official D books, before the more
advanced readings ?
I guess many beginner D programmers will thank you :)
Because a few month ago I've been that beginner D programmer,
and sadly I've completely missed this perfect tutorial. And
I've just explained you why...
So why not supposing other programmers will have the same
problem, and maybe miss it just like me ?
No, i have the same issue with the website. Tutorialspoint may
have issues as ag0aep6g pointed out but its very much to the
point. I prefer to look up information on tutorialspoint compared
to the D website.
Lets say Arrays:
* D website starts with Pointers, then Static Arrays, then
Dynamic Arrays then ... A person may simply say: "I just want to
know how to write a array, i do not need a tutorial talking about
the different types, because most of my work is simply standard
arrays".
Instead of splitting the information in different chapters, its
so much text on a single page. Tutorialspoint simply shows the
basic information and that is what i need 90% of the time.
How about Modules:
* D website starts with a big blog of texts Module,
ModuleDeclaration DeclDefs DeclDefs. What am i reading. Chinese?
By the time you see the visual text how to declare a module, you
are already 2 pages down.
Tutorialspoint simply shows how to declare modules. Basic, fast
...
Tutorialspoint indeed misses a lot of information but D website
has unreadable information overload. Useful for people who have
time to read half a day but as somebody programming and wanting
to quickly look up information. D website is not useful. Its
actually counter intuative.
It feels academic in design, not functional. You expect to get
simple example and the more advanced items under "advanced".
I have the same issue with the Library. The flow of information
is bad, too much walls of text, with too much assumption that the
programmer reading it is familiar with the more advanced features
or programming knowledge. Links and references to variables that
frankly, are unneeded. If it takes 15 minutes to know in
std.parallelism that you can not get a thread ID in a simply
way... then the purpose as a information source fails.
A simple:
https://dlang.org/phobos/std_datetime_date.html
Why do you need to wade past 2 pages for
jan
feb
mar
apr
may
jun
jul
aug
sep
oct
nov
dec
sun
mon
tue
wed
thu
fri
sat
...
Then the whole Jump to: 2, Jump to: 2, Jump to: 2 ...
Function naming...
Expect: bool validTimeUnits(string[] units...);
Gets: pure nothrow @safe bool validTimeUnits(string[] units...);
... Visual noise that is not important. Details like that need to
be in a sub page.
People care about the function, parameter, return type. The rest
is "advanced" and only useful under specific sitations.
After months i still do not use the library/documentation. I end
up googling for examples or use tutorialspoint for some quick
basic lookup's. If i am really stuck i may go into the library
and get frustrated with the wall of text. Its is too much a time
sink, while its supposed to be a help.
I do not know how to explain it but the documentation is at times
more frustrating then the issue i am trying to solve. If i had to
give a score, the D documentation is at best 4/10. Its not the
lack of information but the simply bad presentation, overflow of
information where you do not need it. No clear separation. Mobile
friendly it is NOT. Even 4K friendly it also not. And plenty of
other issues.
