Mockup of my doc dream ideas

[rcorre via Digitalmars-d]

On Friday, 25 December 2015 at 14:24:34 UTC, Bubbasaur wrote:
>
> What happens when I see a DOC with comments is that sometimes 
> the comments are more clear than the Doc itself, or there are 
> tips or tricks that was not "well" documented.
>
> Bubba.

If the comments are more clear than the Doc, then they should 
_be_ the doc. Similarly, useful tips and tricks should probably 
be included as doc examples. In other words, I think we should 
encourage contribution to official documentation rather than 
dividing between official docs and user comments.

This does raise the bar to entry though, so maybe a suggestion 
box could be a nice middle ground.