Example within documentations of D seriously need some improvement.

[Matthew Ong]

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.

-- 
Matthew Ong
email: ongbp at yahoo.com