The problem with the comment feature on the old site wasn't simple neglect. People posted mostly support questions, which should have been sent to the -users list or the commercial support dept (both commercial and OSS users shared the site).
The old site did have the capability to fwd comments to anyone's email in-bin. The people cc'd may have neglected these emails, or may have responded directly to the person without posting followups to the docs site (in which case it would appear to someone like Sebastien that the commenter was never helped). The commenters were mostly people who seemingly weren't aware of the already existing channels for getting technical help. Hardly anyone posted any comments or questions about the docs themselves. So, if we add this, it might turn out we just need to cc all the comments to the -users and -dev lists, or wherever "help me!" questions should ordinarily go. Jessica T. On Fri, Aug 16, 2013 at 4:37 AM, Radhika Puthiyetath < radhika.puthiyet...@citrix.com> wrote: > 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 >
