launchpad developmentThis 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:
- the variety of experience levels in our users
- and the complexity of some of our workflows.
We have three tools that help us explain to users what they need to do and how Launchpad will react:
- the UI text itself
- pop-up help
- the help wiki and other additional materials, such as screencasts.
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:
- many if not most Launchpad users are likely to have a key already
- the process of generating and uploading the key is done outside that page
- explaining the process in the text would make the page cluttered and harder to use.
Pop-up help
So, pop-up help is useful when:
- you want to add further explanation for less experienced people
- you need to describe a process that's necessary to what the user wants to achieve on that page but is either too long to fit on the page or is not achievable directly on that page
Help wiki
The Help wiki is useful when:
- you're describing a process that involves more than one Launchpad page
- you're talking about workflows or policies that are about more than what to click where.
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:
- re-use pop-ups
- keep the reader's attention
- assure users that pop-up help will give them the answer they need without fuss.
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
Keep it simple: minimize sub-clauses in sentences. Aim for one idea or action per sentence. Start a new paragraph when dealing with a new concept. Use shorter words, where possible.
Write in small chunks: write about concepts one at a time and in the order your reader needs to know about them. Split processes into steps.
Show don't just tell: use examples to demonstrate what you're describing. Use cropped screen-shots.
Establish a relationship with the reader: write in the second person (i.e. "upload your branch", not "the user should upload their branch"). Be friendly.
Don't state the obvious.
Offer supplemental information: link to further reading where it won't throw the reader off-course.
Links
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:
- it helps people with screen readers
- it helps prevent blindness to a repeated phrase such as "Help on this topic"
- it should assure the user that the link will help them.
Place parentheses around the link text to show that it's separate from the rest of the text.
