Example within documentations of D seriously need some improvement.

[Jacob Carlborg]

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