cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sonny Chhen <>
Subject RE: [DOCS] Proposed technique for making tooltips from doc XML files
Date Mon, 15 Oct 2012 22:35:02 GMT
Hello All,

I have updated the functional spec on this feature at the link below.

Please let me know if you have any questions or concerns.

Thanks You and Best Regards,

Sonny H. Chhen
Manager of User Interface & User Experience | Citrix Systems - CloudPlatform
4988 Great America Parkway, Santa Clara, CA  95054, USA             

-----Original Message-----
From: David Nalley [] 
Sent: Tuesday, October 09, 2012 6:51 PM
Subject: Re: [DOCS] Proposed technique for making tooltips from doc XML files

On Tue, Oct 9, 2012 at 3:48 AM, Jessica Tomechak <> wrote:
> -----Original Message-----
>> From: David Nalley []
>> Sent: Friday, September 28, 2012 6:43 PM
>> To:
>> Cc:
>> 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 
>> <>
>> 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 page points to the 
> non-ASF page, which in 
> turn points to the non-ASF 
> page The actual feature 
> we're talking about is tracked in bug
> 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)


View raw message