On 2011-05-27 09:35, Matthew Ong wrote:
Hi,
From what I can see,...
The documentation seems to be making something simple harder to
understand with lots of noises added. It is scattered all over the
places. Many information Seem like a lot of dark/unwritten known by only
a few persons.
1) There is No clear organizations. Associated to the syntax being
describe. Like: what is the default encapsulation access modifier for
class/struct/interface/enum/template/mixin/... where are they
documented? There might be more similar broken/implied.
2) When describing a concept with syntax there most if not all example
uses foo/bar and not work/payment? (If you get the sideline grin)
Doing some sort of Neural Linguistic Programming to 'suggest' dumping
someone down? If documentation trying to make a fool out of readers so
that they 'appear' to be experts? Or documentation are there to help
developer code better. Forum is available, I am grateful for the people
that has kindly shown me around with sample code.
3) Is not making a new language purpose to make ease the developer mind
so that they can be free to think about how to model business logic
rather than be busy trying to figure out what is that strange thing for?
4) Not much working example in the html documentaions and not
centralise. Only code fragments, with lots of foo & bar again...
Yes. I have seen:
http://www.dsource.org/projects/tutorials/wiki/ArraysCategory
http://www.dprogramming.com/tutorial.php
Plenty more I would expect...
True mastery is to make the complex model easy to understand not not
simple one to be complex to understand.
The best type of tutorial and documentation format I have seen so far
and yet simple to understand are shown here.
http://www.w3schools.com/php/php_operators.asp
They designed it in a way that those poor junior developer can copy and
paste and still have a working program.
D might consider seriously and carefully how to rework the
Yes. That URL is better than Java tutorial documentation.
Yes, I am ranting. With good reasons. Hopefully for the best of D.
The documentation on the DigitalMars site is more of a language
reference than a tutorial. It's probably not the best place to start but
when you know the language is good to be able to look some odd syntax
you rarely use.
--
/Jacob Carlborg
