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.
