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
