On Tue, Oct 9, 2012 at 3:48 AM, Jessica Tomechak <jessica.tomec...@gmail.com> wrote: > -----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
Thanks for answering all of my questions. This actually is a bigger deal than I expected. So let me make some presuppositions and tell me where/if I've gone wrong. I assume this effectively means that in every release cycle going forward, docs will have to be done by code freeze? Particularly for things that link out, you'll be needing to know the URL for those bits of documentation, etc, which will be on the docs site. How does this handle l10n? E.g. if my locale is set to Russian for the UI, are you going to load Russian tooltips, or English tooltips? (ideal behavior is to default to Russian if it exists, but fall back to English if it doesn't) --David
