discuss disqus

Brad Anderson via Digitalmars-d digitalmars-d at puremagic.com
Wed Jul 30 10:32:39 PDT 2014


On Wednesday, 30 July 2014 at 13:10:35 UTC, Wyatt wrote:
> On Wednesday, 30 July 2014 at 00:40:09 UTC, Brad Anderson wrote:
>>
>> Andrei did say forum integration would be prefered back when 
>> you mentioned it[1]. The more I think about this though the 
>> more I think you are right that wiki would be superior to 
>> comments but I share your concern for wiki comments being 
>> terrible.
>>
> Wikifying the whole of the documentation itself would be more 
> useful than just using it for the comments.  I'm not very fond 
> of that, personally (it tends to look generic and mediocre), 
> but it has paid dividends in Gentoo and Arch.  And as an added 
> benefit, it's relatively easy to get a broad view of what's 
> changing and revert vandalism.
>
>> Thinking about this even more I've come to the conclusion that 
>> there are two main use cases to justify user comments on 
>> documentation pages: 1. Asking questions. 2. Supplemental 
>> documentation. Neither of these is well solved by user 
>> comments (whether by disqus or forum).
>>
> Thank you!  I've been saying this since at least last year and 
> I'm glad I'm not the only one.
>
>> The first use case, asking questions, is best addressed by 
>> something like Stack Overflow.
>>
> Or D.learn.

If D.learn could be integrated with the documentation so that 
questions about a particular function are shown then sure. I 
think that'd be enough. While not essential, voting on answers 
and marking a response as the correct solution are valuable 
features too. Those would have to be some sort of overlay feature 
on the web forum which is something I know Vladimir has been 
reluctant to do in the past (people talking about something like 
votes that not everyone can see could be
confusing).

Implementing this might be as simple as a button that says Ask A 
Question which takes them to a forum post with the FQN of the 
symbol included in the subject line. Then the forum could have an 
API for querying all questions with that FQN that the 
documentation could make use of.

>
>> The second use case, supplemental documentation, is a perfect 
>> fit for wiki integration.
>>
> Serious question: what exactly is "supplemental documentation"?
>  In my view, if it's good enough to be considered 
> documentation, it belongs in the documentation.  Anything else 
> is just pussy-footing around.
>
> -Wyatt

What comes to mind for me are micro-tutorials. When I was using 
PHP back in the day I'd be trying to do something and I'd find 
the function I could use to do it but figuring out exactly how to 
make use of the function to accomplish what I wanted wasn't 
always straight forward. The PHP comments would often have 
comments along the lines of "Trying to do X? Here's how...".

Cluttering up the main documentation with lots of these types of 
things would choke out the essential material the documentation 
covers with a lot of material not everyone needs to know. You 
could think of it like an appendix.


More information about the Digitalmars-d mailing list