-----Original Message----- > From: David Nalley [mailto:da...@gnsa.us] > Sent: Friday, September 28, 2012 6:43 PM > To: cloudstack-dev@incubator.apache.org > Cc: cloudstack-dev@incubator.apache.org > Subject: Re: [DOCS] Proposed technique for making tooltips from doc XML > files > > Sorry for top posting. > Where is this roadmap you speak of? Functional spec? > Link to the discussion about the feature? (or is this the initial > discussion?) Link to demo? > > Does phraseid or any other tags you will use break anything in publican > builds? Is this a connection over the network to get access to the content > or are you bundling docs in the -client package? I understand what you are > trying to do, but don't understand the mechanics of how you are planning to > deliver the content. > > > --David > > On Sep 28, 2012, at 1:44 PM, Jessica Tomechak <jessica.tomec...@gmail.com> > wrote: > > > There is an upcoming feature on the roadmap called context-sensitive > help. > > We want to add help links and tool tips (1-sentence rollover popups) > > to the CloudStack UI. > > > > I've been working with the CloudStack UI guys on a way to pull tooltip > > strings right from the doc source files. This way, we don't have a > > separate resource file with out-of-sync texts. We can simply tag > > phrases in the XML source with unique identifiers, then the code can > > feed those strings into the UI by mapping our text identifiers to the > > UI element identifiers. We did a little demo of this and it works really > well. > > > > Before I set about tagging everything in the doc repo with these > > tooltip identifiers, I wanted to see if we have any comments on the > following: > > > > (1) Is context sensitive UI help high priority for Apache CloudStack? > > (2) Is the technique we came up with optimal? > > > > For our demo, we added human-readable IDs to the descriptions of some > > dialog box input fields, like so: > > > > <section id="creating-network-offerings"> > > <title>Creating a New Network Offering</title> > > <para>To create a network offering:</para> > > > > ... > > <listitem><para>Click Add Network Offering.</para></listitem> > > <listitem><para>In the dialog, make the following choices:</para> > > <itemizedlist> > > > > <listitem><para>Name. <phrase id="helpNetworkOfferingName">Any desired > > name for the network offering</phrase></para></listitem> > > > > <listitem><para>Description. <phrase > > id="helpNetworkOfferingDescription">A > > short description of the offering that can be displayed to > > users</phrase></para></listitem> > > > > Jessica T. > > CloudStack Tech Pubs >
To answer David's Qs: No, this doesn't break the publican build. Publican takes no notice of the <phrase> tags at all. Link to discussion about the tooltip feature? Looking through cloudstack-dev archives, it looks like context-sensitive UI help links and tooltips have not been discussed as an Apache CloudStack feature. So maybe we should start that discussion! Functional spec? Don't think there is one. But I can ask the developer I worked with on the demo to write one up. Is it a connection over a network? No, not for tooltips. The phrases are pulled out of the /doc directory during the build, they are put into an intermediate JSON resource file, and then placed in the UI. You wouldn't need to hit the /doc directory live at runtime to get the popups. I don't know whether you have to ship the JSON file along with the build. Where you *would* need a network connection is for any Help links that go to larger topics. This is the sort of Help link you typically find in the upper-right corners of UI elements like forms, panels, tabs, and pages. We have envisioned making those go to URLs on the CloudStack documentation site -- most help links these days go out to the product information portal, rather than bundling a big help file with the software. This depends on the assumption that CS users have access to the Internet. If that assumption isn't good, we should re-think. Where is the roadmap? The roadmap link on the main cwiki.apache.org page points to the non-ASF page http://www.cloudstack.org/software/roadmap.html, which in turn points to the non-ASF pagehttp://wiki.cloudstack.org/display/PM/Campo. The actual feature we're talking about is tracked in bug http://bugs.cloudstack.org/browse/CS-14878. I hope this information is helpful. Sorry the email is long. That was a lot of questions! Jessica T. CloudStack Tech Pubs
