This is a rough and growing guide to using Launchpad's pop-up help system.

Please update it with your thoughts and any positive/negative experiences you've had while using the pop-up help system. Please file bugs about the pop-up JS etc itself against launchpad-foundations.

When to add pop-up help

While our aim is for the Launchpad UI to be self-explanatory, two things make that harder:

We have three tools that help us explain to users what they need to do and how Launchpad will react:

UI text

The UI text should provide enough information for most Launchpad users most of the time. It should also relate directly to what the user can do on that page.

Importantly, the UI text should be concise: if a user can't glance at the text and know whether its useful to them, it's no good.

As an example: the +editpgpkeys page.

The introduction explains why OpenPGP keys are useful in Launchpad but doesn't say how to generate a key or push it to a public keyserver. That's because:

Pop-up help

So, pop-up help is useful when:

Help wiki

The Help wiki is useful when:

Writing pop-up help

Where pop-up help files live

Pop-up help files all live in the LP tree. Where you put them depends on which page you plan to call them from:

launchpad.net/+help -> lib/lp/registry/help
launchpad.net/+help/soyuz -> lib/lp/soyuz/help
bugs.launchpad.net/+help -> lib/lp/bugs/help
blueprints.launchpad.net/+help -> lib/blueprints/help
answers.lauchnpad.net/+help -> lib/lp/answers/help
translations.launchpad.net/+help -> lib/translations/help
code.launchpad.net/+help -> lib/lp/code/help

Example: https://translations.launchpad.net/+help/permissions-policies.html lives at lib/lp/translations/help/permissions-policies.html

Format

Each pop-up should, ideally, answer one question only. If you need to cover more, link to another pop-up or to the help wiki. This will help us to:

While an artificial word limit is probably unhelpful, you may want to ask yourself whether your pop-up should be split into two if you find yourself writing more than 400 words.

Template

<html>
  <head>
    <title>Help topic title</title>
    <link rel="stylesheet" type="text/css"
          href="/+icing/yui/current/build/cssreset/reset.css" />
    <link rel="stylesheet" type="text/css"
          href="/+icing/yui/current/build/cssfonts/fonts.css" />
    <link rel="stylesheet" type="text/css"
          href="/+icing/yui/current/build/cssbase/base.css" />
  </head>
  <body>
    <h1>Help topic title</h1>

    <p>
      Help content
    </p>

    <p>
      Optional link to further help.
    </p>
  </body>
</html>

Style

To other pop-ups within the same directory in the tree: /+help/pop-up-name.html To other pop-ups elsewhere in the tree: use the full URL To the help wiki: link as normal but use target="_blank" to avoid opening the page in the pop-up.

Link to the help wiki if it has further reading on the subject.

Images

You can and should use images in your pop-ups. Store them in the images directory that lives under the directory where your help file is saved.

Calling pop-up help

To add pop-up help to a page, link it as normal but with target="help".

Example: <a href="/+help/openpgp-keys.html" target="help">Learn more about OpenPGP keys</a>

Your link text should be relevant to the help, because:

Place parentheses around the link text to show that it's separate from the rest of the text.

PopUpHelp (last edited 2009-08-21 10:10:33 by danilo)