cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chip Childers <chip.child...@sungard.com>
Subject Re: [DISCUSS] Comments on html docs and apidocs
Date Tue, 26 Feb 2013 14:02:39 GMT
On Tue, Feb 26, 2013 at 08:50:04AM -0500, Sebastien Goasguen wrote:
> 
> On Feb 26, 2013, at 3:00 AM, David Nalley <david@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/listNetworkOfferings.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

Mime
View raw message