Better docs for D (WIP)

[Israel via Digitalmars-d-announce]

On Thursday, 31 December 2015 at 01:32:56 UTC, Adam D. Ruppe 
wrote:

> The D leaders know how important examples are. We are often 
> told adding more is low hanging fruit. I completely agree. But 
> that's not ALL we need. He wants examples to get started, yes, 
> but he also wants understanding to go beyond examples. That's 
> where text helps. That's where understanding the function 
> signatures help. Eventually, when people go to write their own 
> libraries, they might want to do Phobos style genericity. You 
> can't do that without understanding the function signatures... 
> and those blobs of text are not understandable.

This is what hits me the most. Thats why we suggested "user 
contributed examples". PHP docs is the only place ive seen this. 
What is your stance on this and if you agree, how would you 
implement it? How would it work?