You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by David Nalley <da...@gnsa.us> on 2013/02/26 09:00:10 UTC
[DISCUSS] Comments on html docs and apidocs
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
Re: [DISCUSS] Comments on html docs and apidocs
Posted by Jessica Tomechak <je...@gmail.com>.
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.puthiyetath@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.childers@sungard.com]
> Sent: Tuesday, February 26, 2013 7:33 PM
> To: cloudstack-dev@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
>
RE: [DISCUSS] Comments on html docs and apidocs
Posted by Radhika Puthiyetath <ra...@citrix.com>.
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.childers@sungard.com]
Sent: Tuesday, February 26, 2013 7:33 PM
To: cloudstack-dev@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
Re: [DISCUSS] Comments on html docs and apidocs
Posted by Chip Childers <ch...@sungard.com>.
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/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
Re: [DISCUSS] Comments on html docs and apidocs
Posted by Sebastien Goasguen <ru...@gmail.com>.
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/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