Mockup of my doc dream ideas

[bachmeier via Digitalmars-d]

On Friday, 25 December 2015 at 15:51:02 UTC, rcorre wrote:
> 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.

I agree with this. The PHP documentation is a mess because of the 
comments.

> 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.

I think there should be link to the wiki for tips and tricks and 
more examples. Sometimes you don't want 10 examples in the 
official docs, even if they will help some users. The main reason 
for using the wiki would be specialized examples.

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

Filing a bug is a better approach. It's best to keep everything 
in one place.