You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Jessica Tomechak <je...@gmail.com> on 2012/10/09 09:48:31 UTC
Re: [DOCS] Proposed technique for making tooltips from doc XML files
-----Original Message-----
> From: David Nalley [mailto:david@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 <je...@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
RE: [DOCS] Proposed technique for making tooltips from doc XML files
Posted by Sonny Chhen <So...@citrix.com>.
Hello All,
I have updated the functional spec on this feature at the link below.
https://cwiki.apache.org/confluence/display/CLOUDSTACK/UI+-+Dynamic+Tooltip
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 [mailto:david@gnsa.us]
Sent: Tuesday, October 09, 2012 6:51 PM
To: cloudstack-dev@incubator.apache.org
Subject: Re: [DOCS] Proposed technique for making tooltips from doc XML files
On Tue, Oct 9, 2012 at 3:48 AM, Jessica Tomechak <je...@gmail.com> wrote:
> -----Original Message-----
>
>> From: David Nalley [mailto:david@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
>> <je...@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
Re: [DOCS] Proposed technique for making tooltips from doc XML files
Posted by Jessica Tomechak <je...@gmail.com>.
>
> -----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Tuesday, October 16, 2012 5:19 AM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: [DOCS] Proposed technique for making tooltips from doc XML
> files
>
> >
> > David,
> > You bring up a question which I meant to ask earlier. Can we be sure
> > that the URLs of doc pages won't change over time? I think we can, if
> > the following is true: Each Help link in the UI links to a page under
> > the correct software version and language on the doc site, like
> > http://incubator.apache.org/cloudstack/docs/4.0.0/en-US/about-zones.html
> .
>
>
> No - we can't be sure of that.
> Our URL will (hopefully) change when we graduate to a TLP - we'll then
> have cloudstack.apache.org as our domain.
>
David,
Sorry, I should have been more specific. I was wondering more about the
last part of the URL, the part that Publican generates. I think those
parts, like "about-zones.html", will always match the XML filenames in the
repo -- and we control those.
I hope, and believe, it's easy enough to set the code up to make it easy to
swap in a different domain. Anyone who's customizing the UI for any reason
will want to do that.
Jessica T.
CloudStack Tech Pubs
>
>
> >
> > I don't know exactly how the UI help would handle l10n. The eng/UI
> > teams would know more. We'd have localized content in different
> > subdirectories in the git repo, just as we have English content in the
> > docs/en-US subdirectory. And the <phrase> tags around the tooltip
> > content would still be there just like all other XML tags, which
> > translators don't touch. So I imagine the UI could pull tooltip
> > content from each language directory in the repo, then at runtime
> > display the right tooltip strings using the same mechanism as is used
> for any other localized UI text.
>
>
> That's not how l10n works in Docbook - take a look at docs/runbook/zh-CN
> which has a Chinese localized version of the 3.0.2 runbook. There's not
> even XML, hence my 'how is this gonna work'
> question.
>
> --David
>
Re: [DOCS] Proposed technique for making tooltips from doc XML files
Posted by David Nalley <da...@gnsa.us>.
>
> David,
> You bring up a question which I meant to ask earlier. Can we be sure that
> the URLs of doc pages won't change over time? I think we can, if the
> following is true: Each Help link in the UI links to a page under the
> correct software version and language on the doc site, like
> http://incubator.apache.org/cloudstack/docs/4.0.0/en-US/about-zones.html.
No - we can't be sure of that.
Our URL will (hopefully) change when we graduate to a TLP - we'll then
have cloudstack.apache.org as our domain.
>
> I don't know exactly how the UI help would handle l10n. The eng/UI teams
> would know more. We'd have localized content in different subdirectories in
> the git repo, just as we have English content in the docs/en-US
> subdirectory. And the <phrase> tags around the tooltip content would still
> be there just like all other XML tags, which translators don't touch. So I
> imagine the UI could pull tooltip content from each language directory in
> the repo, then at runtime display the right tooltip strings using the same
> mechanism as is used for any other localized UI text.
That's not how l10n works in Docbook - take a look at
docs/runbook/zh-CN which has a Chinese localized version of the 3.0.2
runbook. There's not even XML, hence my 'how is this gonna work'
question.
--David
Re: [DOCS] Proposed technique for making tooltips from doc XML files
Posted by Jessica Tomechak <je...@gmail.com>.
-----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Tuesday, October 09, 2012 6:51 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: [DOCS] Proposed technique for making tooltips from doc XML
> files
>
> On Tue, Oct 9, 2012 at 3:48 AM, Jessica Tomechak <
> jessica.tomechak@gmail.com> wrote:
> > -----Original Message-----
> >
> >> From: David Nalley [mailto:david@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
> >> <je...@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
>
David,
You bring up a question which I meant to ask earlier. Can we be sure that
the URLs of doc pages won't change over time? I think we can, if the
following is true: Each Help link in the UI links to a page under the
correct software version and language on the doc site, like
http://incubator.apache.org/cloudstack/docs/4.0.0/en-US/about-zones.html.
I don't know exactly how the UI help would handle l10n. The eng/UI teams
would know more. We'd have localized content in different subdirectories in
the git repo, just as we have English content in the docs/en-US
subdirectory. And the <phrase> tags around the tooltip content would still
be there just like all other XML tags, which translators don't touch. So I
imagine the UI could pull tooltip content from each language directory in
the repo, then at runtime display the right tooltip strings using the same
mechanism as is used for any other localized UI text.
Jessica T.
CloudStack Tech Pubs
Re: [DOCS] Proposed technique for making tooltips from doc XML files
Posted by David Nalley <da...@gnsa.us>.
On Tue, Oct 9, 2012 at 3:48 AM, Jessica Tomechak
<je...@gmail.com> wrote:
> -----Original Message-----
>
>> From: David Nalley [mailto:david@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 <je...@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