On 11 March 2014 14:09, Dicebot <pub...@dicebot.lv> wrote: > On Monday, 10 March 2014 at 15:08:07 UTC, Andrei Alexandrescu wrote: > >> On 3/10/14, 7:00 AM, Dicebot wrote: >> >>> I still don't like disqus :) >>> >> >> Are there better such systems available? >> > > I don't like the very concept of comments integrated with the docs and > can't accept PHP example as authority. It just feels very intrusive > > wiki + stackoverflow + forum.dlang.org generate much more natural user > documentation > > I don't like doc-integrated comments either.
A possible consequence is that people will simply stop improving the docs, because "workarounds" or extra explanations will be available in the comments. Something like this happens in the AngularJS documentation, for example. There, the docs can be incomplete or even out of date, so you have to look at the comments. Of course, if the docs are out of date regardless, this can be considered a good thing.