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.
