incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastien Goasguen <run...@gmail.com>
Subject Re: [DISCUSS] Comments on html docs and apidocs
Date Tue, 26 Feb 2013 13:50:04 GMT

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 ?

> 
> --David


Mime
View raw message