discuss disqus

[Wyatt via Digitalmars-d]

On Wednesday, 30 July 2014 at 17:32:40 UTC, Brad Anderson wrote:
>
> 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.
>
I think I suggested something like this at one point.  It's at 
least not abhorrent.  Except for voting systems.  I have serious 
misgivings about those.

> 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...".
>
This sounds suspiciously like...a cookbook?  Since we're 
apparently going all-in on doc fanout, how about a "more 
examples" wiki page linked at the bottom for that sort of stuff?  
And as an added bonus, this lets us be clear on licensing of 
these snippets, too.  If they're really good, we might even 
decide to promote them.

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

Ideally, I think the examples in the documentation should be 
sufficient to demonstrate the capabilities of the 
module/function/etc., but I acknowledge reality isn't always so 
kind.  Not sure what else to say here.

-Wyatt