Size: 3995
Comment:
|
Size: 7127
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
## page was renamed from DeveloperDocumentation/UserInterfaceChecklist These are low-level design guidelines for Web pages, e-mail messages, and other Launchpad output. They cover common mistakes, and are not a substitute for having an interface designer involved in the design of any visible change. |
= User interface text guidelines = |
Line 4: | Line 3: |
== Text == | If you have access to it, you should get to know Canonical's own style guide. |
Line 6: | Line 5: |
These guidelines apply to Web pages, e-mail messages, Atom feeds, IRC notifications, and any other media used in the future. | However, Launchpad has its own tone of voice and audience. We have developed our own approach to UI text and, while we're tweaking our approach to make sure Launchpad feels like part of the Canonical family, the way we write UI text in Launchpad is described here. == Tone of voice == Thousands of people, all around the world, use Launchpad to work on software projects. Launchpad is not what is important: it is just a way for those people to work on another project that has its own identity and personality. Similarly, the majority of Launchpad page requests are made from countries whose primary language is not English. Bearing both those things in mind, our tone voice has become: * friendly and direct but not chummy or inappropriate * technical yet jargon-free * unapologetic and positive * clear and simple: English is a second or third language for most people using Launchpad * understated and unobtrusive: Launchpad should get out of the user's way. == Check list == * Write in short, active sentences: try to have no more than one main idea per sentence. * Speak directly to the person using the page: "You can...", rather than "the user can..." * Use as few words as possible, without compromising meaning, precision or clarity. * When explaining how to do something, put the result first: e.g. "To gain over 9000 karma points click 'Karmageddon'", rather than "Click 'Karmageddon' to..." * Use the singular "they/their/them" rather than gender-specific pronouns. * Use British English. Consult The [[http://www.economist.com/research/StyleGuide/|Economist]] (or Canonical, if you have access) style guide. * Avoid slang or other colloquialisms. * Use pop-up help if your UI text is longer than one or two sentences, or there's something people will need to read only once or twice. * Will the users you have in mind have to think more about the way you've written something than what you're trying to say? * Have you asked someone else to review your UI text? == Common mistakes == These guidelines apply to web pages, e-mail messages, Atom feeds, IRC notifications, and any other media used in the future. |
Line 37: | Line 67: |
== First person, second person == First person (I, me, my) should be used only in controls (buttons, checkboxes, radio buttons, etc). Everything else, including headings, should use second person (you, your). As a user, you interact with the control, so it speaks as your voice (e.g. "Yes I do"). The rest of the web page is generated by Launchpad, and as such should speak with Launchpad's voice (e.g. "Yes you do"). |
|
Line 49: | Line 85: |
== Changing things or editing them == Only documents are edited, everything else is changed. Only use 'Edit' to describe actions where a document or something document-like is being edited. e.g. A project description is a paragraph of text, and can be edited. The project's details, considered as a whole, can be changed. |
|
Line 73: | Line 114: |
== Explaining things == We explain things in three ways: * UI text in the flow of the page: this should be minimal and concise, to avoid text-overload * pop-up help: additional information necessary to understand what's on the current page * the help wiki: additional information necessary to understand workflows and other broader topics. UI text should always be direct and clear, with enough explanation that a new user can decide whether they need to get further information or disregard the feature. |
User interface text guidelines
If you have access to it, you should get to know Canonical's own style guide.
However, Launchpad has its own tone of voice and audience. We have developed our own approach to UI text and, while we're tweaking our approach to make sure Launchpad feels like part of the Canonical family, the way we write UI text in Launchpad is described here.
Tone of voice
Thousands of people, all around the world, use Launchpad to work on software projects. Launchpad is not what is important: it is just a way for those people to work on another project that has its own identity and personality.
Similarly, the majority of Launchpad page requests are made from countries whose primary language is not English.
Bearing both those things in mind, our tone voice has become:
- friendly and direct but not chummy or inappropriate
- technical yet jargon-free
- unapologetic and positive
- clear and simple: English is a second or third language for most people using Launchpad
- understated and unobtrusive: Launchpad should get out of the user's way.
Check list
- Write in short, active sentences: try to have no more than one main idea per sentence.
- Speak directly to the person using the page: "You can...", rather than "the user can..."
- Use as few words as possible, without compromising meaning, precision or clarity.
- When explaining how to do something, put the result first: e.g. "To gain over 9000 karma points click 'Karmageddon'", rather than "Click 'Karmageddon' to..."
- Use the singular "they/their/them" rather than gender-specific pronouns.
Use British English. Consult The Economist (or Canonical, if you have access) style guide.
- Avoid slang or other colloquialisms.
- Use pop-up help if your UI text is longer than one or two sentences, or there's something people will need to read only once or twice.
- Will the users you have in mind have to think more about the way you've written something than what you're trying to say?
- Have you asked someone else to review your UI text?
Common mistakes
These guidelines apply to web pages, e-mail messages, Atom feeds, IRC notifications, 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 |
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>) |
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.
First person, second person
First person (I, me, my) should be used only in controls (buttons, checkboxes, radio buttons, etc). Everything else, including headings, should use second person (you, your).
As a user, you interact with the control, so it speaks as your voice (e.g. "Yes I do"). The rest of the web page is generated by Launchpad, and as such should speak with Launchpad's voice (e.g. "Yes you do").
Notifications, warnings, and errors
Follow the guidelines specified in AlertMessages.
Taking or cancelling actions
The actions at the end of a form should consist of a button, followed by the word "or" and a Cancel link:
( 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.)
Changing things or editing them
Only documents are edited, everything else is changed. Only use 'Edit' to describe actions where a document or something document-like is being edited.
e.g. A project description is a paragraph of text, and can be edited. The project's details, considered as a whole, can be changed.
Create or Register actions
Use "Register" when the thing exists outside of Launchpad. Users register projects, series, milestones, and teams in Launchpad.
Use "Create" when the thing exists exclusively in Launchpad. Users create PPAs, recipes, and bugwatches in Launchpad.
Some users are confused or angered when they read "create" for a thing that they know exists elsewhere. They believe Launchpad is claiming authority over the thing. This issue can often be avoided by selecting the correct verb.
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.
Explaining things
We explain things in three ways:
- UI text in the flow of the page: this should be minimal and concise, to avoid text-overload
- pop-up help: additional information necessary to understand what's on the current page
- the help wiki: additional information necessary to understand workflows and other broader topics.
UI text should always be direct and clear, with enough explanation that a new user can decide whether they need to get further information or disregard the feature.