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? --David
