Personally, I liked the interface. One of my previous employers, an Open Source org, employed this system for the documentation site.
If we have some mechanism in place to receive the comments in the Inbox of the author, even more awesome ! -----Original Message----- From: Chip Childers [mailto:chip.child...@sungard.com] Sent: Tuesday, February 26, 2013 7:33 PM To: cloudstack-...@incubator.apache.org Subject: Re: [DISCUSS] Comments on html docs and apidocs On Tue, Feb 26, 2013 at 08:50:04AM -0500, Sebastien Goasguen wrote: > > On Feb 26, 2013, at 3:00 AM, David Nalley <da...@gnsa.us> wrote: > > > Hi folks, > > > > At the Barcamp before ApacheCon someone showed off the > > comments.apache.org system. > > Essentially it allows you to embed discussion threads in otherwise > > static documentation. Disqus is a similar commercial tool. > > > > I quickly generated the 4.1 APIDocs after adding the comment snippet > > to the base (and yes it will need some polish) > > > > You can try this out on the root admin api calls here (none of the > > domain admin or user api calls pages have the code): > > http://people.apache.org/~ke4qqq/apidocs > > > > In Example: > > http://people.apache.org/~ke4qqq/apidocs/root_admin/listNetworkOffer > > ings.html > > > > You can leave comments etc. > > > > We had a similar system on the old docs.cloudstack.org - and I was > > personally not a fan - people left messages/questions/etc; and > > received little or no response. This system has the ability to > > notify a mailing list (I know, another way of generating email :) ) > > of each comment. And I'd personally be the first person to rip this > > out if it's neglected. Often times though, annotating existing > > documentation can be helpful. I'd consider this on the html docs on > > incubator.apache.org/cloudstack/docs as well if it works well on the > > API stuff. > > > > Thoughts? > > Do you think we can keep up with the comments? Push folks asking > > questions to the user list, cultivate the content, etc? > > Anyway to send the comments to JIRA on dedicated tickets for each api call ? > That might make this tolerable IMO. I'm personally not interested in seeing a forum-style interface. We are already managing too many interactions right now, and another one worries me. -chip
