cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jessica Tomechak <jessica.tomec...@gmail.com>
Subject Re: [DOCS] Proposed technique for making tooltips from doc XML files
Date Tue, 16 Oct 2012 06:56:39 GMT
-----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
> >> <jessica.tomechak@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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message