launchpad development|
⇤ ← Revision 1 as of 2009-01-12 13:52:59
Size: 6980
Comment: Moved from l.c.c
|
Size: 0
Comment: This documentation has all been moved to other pages now.
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| As Launchpad is becoming both bigger and more sophisticated, it is increasingly important for developers to be able to get small UI-related things right themselves, and for reviewers to be able to check these things. So here are some low-level guidelines. == Web pages == * Is the page necessary? Or is it small enough to be an expandable section of another page? * Imagine you're in the target audience for the page, but you've never seen it before. Reading it, would you understand what's going on? Does it need embedded help? * Is the `<title>` appropriate and context-sensitive? If the page is the Overview of an independent entity (e.g. a person or a package), does the `<title>` end with "in Launchpad"? * Are at least two of the tabs enabled? If not, the location hierarchy has likely gone too deep. * With those tabs that are enabled, do all of them go to other facets of the last object in the location bar? * In any form, what happens if you skip a compulsory field? What happens if you enter disallowed characters? What happens if you enter 200 KB of text? * After finishing with the page, is there anywhere you'll very likely want to go next? Is that destination linked to? * Does the page look elegant and well-balanced? == Text == These guidelines apply to Web pages, e-mail messages, and any other media used in the future. ||'''Don’t use this''' ||'''Use this instead''' || ||abort ||stop || ||above ||this, these || ||click ||''nothing'' || ||below ||this, these || ||DOAP ||''nothing''|| ||FOAF ||''nothing''|| ||illegal ||not allowed|| ||invalid ||incorrect ''(or more specific error)'' || ||just ||''nothing'' || ||Malone ||Launchpad ''or'' Launchpad’s bug tracker || ||Note: ||''nothing'' || ||Note that ||''nothing'' || ||please ''(unless announcing serious inconvenience)'' ||''nothing''|| ||Rosetta ||Launchpad ''or'' Launchpad Translations || ||simply ||''nothing'' || ||Soyuz ||''nothing'' || ||the following ||this, these || ||the form ||''nothing'' || ||this form ||''nothing'' || ||this page ||''nothing'' || ||to the left ||''better page layout'' || ||to the right ||''better page layout'' || ||* ||''better text ordering'' || ||! ||''nothing (or, if in real danger, `<strong>`)'' || == Template code == * Template code should be indented with two spaces. ||'''Don’t use this''' ||'''Use this instead''' || ||`<b>` ||`<th>`, `<dt><dfn>`, `<strong>` || ||`<br>` ||`<li>`, `<div>`...`</div>` || ||`metal:fill-slot="pageheading"`||`metal:fill-slot="main"`|| ||`<h3>` ''(unless `<h2>` is used earlier in the page)'' ||`<h2>`, `<div>` || ||`<hr>` ||''nothing'', `<table class="listing">` || ||`<i>` ||''nothing'', `<em>`, `<var>` || ||`onclick=` ||''Mochi``Kit to attach event handlers to elements (and to create the elements too, if they do nothing without Java``Script).<<BR>>See the JavaScriptStyleGuide for more information.''|| ||`style=` ''(unless this style is used nowhere else)'' ||''HTML elements, classes'' || ||`<ul><li tal:repeat="bar bars"`...||`<ul tal:condition="bars"><li tal:repeat="bar bars"`...|| ||`<div tal:replace=`...<<BR>>`<span tal:replace=`...||`<tal:one-word-summary replace=`... <<BR>> `<tal:one-word-summary replace=`... <<BR>> ''(functionally identical, but more informative for those reading the code later)''|| ||' ''(ASCII single quote used for an apostrophe)'', ' || &``#8217; ''or'' ’ ''or'' ’ || ||"foo" ''(ASCII double quotes)'', " || “ ''and'' ” ''or'' “ ''and'' ” || ||'foo' ''(ASCII single quotes)'' || ‘ ''and'' ’ ''or'' ‘ ''and'' ’ || See also PageTemplateHacking, which may be mergable with this page. == Capitalization == * Buttons should be Headline Case; the last word capitalized, and all other words capitalized except those three letters or fewer that are prepositions, articles, or conjunctions. * Everything else should be sentence case, including headings, checkbox labels, menu items, and e-mail Subject lines. == Menu items == * Menu items should start with a verb if practical. * ''use of "Show", "List", or "View" TBA'' == Notifications, warnings, and errors == Follow the guidelines specified in AlertMessages. == Cancelling actions == The actions at the end of a form should consist of a button, followed by the word "or" and a Cancel link: ||<tablestyle="background-color: #eee;">( Summary of Action ) or __Cancel__|| The "Cancel" link should return you to the page you came from. (To get this link, define the `cancel_url` @property in the browser class.) == E-mail messages == These guidelines apply to all e-mail messages: * Don't wrap paragraphs manually in the message template. The e-mail machinery can do this more consistently (especially if the message contains variables). * If the message is from a subscription, the footer should consist of three lines: * the URL of the relevant resource (''e.g.'' the bug report) * "You are ''precise reason for getting this message''" * "To unsubscribe: <''URL of unsubscription page''>" ''?? -- TBD'' These guidelines apply to notifications not being sent on behalf of a Launchpad user: * From addresses should be `@launchpad.net`, not `@canonical.com` or `@ubuntu.com`, and should have a display name starting with "Launchpad". * The Web page that tells you you're being e-mailed should say what the From address will be. * The Subject line should be informative, and use sentence case. * The body text should be copyedited by someone fluent in the language being used. == Comments and suggestions == I've struggled with writing instructions that do not use 'click'. I often use phrasing like 'choose', 'activate' or 'follow'. None are satisfactory. I do not use 'click' nonetheless. -- CurtisHovey Curtis, I think the ''ideal'' is that you just say what the reader should do and why they should do it, and assume that the controls are obvious enough that you don't need to spell out how they should do it. So, words like 'choose' or 'follow' should be unnecessary in a perfectly communicative page. Now, it's really hard to reach that ideal, so we'll sometimes still need 'choose' and 'follow'. Matthew, maybe you can comment further. -- SteveAlexander One common pattern is, instead of saying "To frobnicate your fizwizzle __click here__", just label the link "__Frobnicate my fizwizzle__". -- mpt |
