[Development] Commentable doc hosting

[Stephen Kelly]

On Wednesday, November 30, 2011 17:57:02 sarah.j.smith at nokia.com wrote:
> Hi
> 
> During the contributors summit at Dev Days in San Fran doc was discussed -
> in few different contexts, including getting folks to contribute to it.
> 
> What about the approach used by some projects of having the canonically
> hosted documentation provide for a forum post style comment feature down
> the bottom of each page of documentation?
> 
> Here's an example of what I mean:
> http://www.php.net/manual/en/control-structures.foreach.php … scroll down
> to see the "User Contributed Notes".
> 
> Obviously the great preference would be for folks to supply doc bug reports
> or patches for problems they see.  But this has a low barrier to entry for
> user contributions, and the possibility for developers on the relevant
> API's to subscribe to the rss feed to pick up contributions and add them is
> always there.  Monitoring via rss should also mean spammy posts can be
> removed if needed too.
> 
> Kevin I guess we already must have some sort of server side stuff over just
> static web pages in order for the javascript based doc search to work.  Is
> something like this feasible with the resources/infrastructure available?
> 
> Thoughts?
> 

The best commentable docs I've seen are in the Django book:

http://www.djangobook.com/about/comments/
http://www.djangobook.com/en/2.0/chapter01/
http://new-media.djangobook.com/djangobook.js
http://stackoverflow.com/questions/1049272/unable-to-find-build-a-commenting-
system-similar-as-at-djangobook

They're paragraph by paragraph instead of at the end, and unobtrusive. You 
don't see them unless you want to see them and you click on them.

Thanks,

-- 
Stephen Kelly <stephen at kdab.com> | Software Engineer
KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company
www.kdab.com || Germany +49-30-521325470 || Sweden (HQ) +46-563-540090
KDAB - Qt Experts - Platform-Independent Software Solutions
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20111130/091a29d6/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20111130/091a29d6/attachment.sig>